diff --git a/AGENTS.md b/AGENTS.md index 8519ff431..23fe26bdd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,8 +16,7 @@ Useful pointers: - `BAZEL.md` for the contributor-facing Bazel build path - `docs/AGENTS.md` for in-repo user and developer documentation - `tools/AGENTS.md` for repo tooling -- `imports.yaml` for subtree ownership and commit pins, an internal file not - present in this public snapshot +- `imports.yaml` for subtree ownership and commit pins - `.cursor/skills/documentation-style/SKILL.md` for docs style - `.cursor/skills/` for root dev-skill symlink fanout - `ai-tooling/user/skills/` and `ai-tooling/dev/skills/` for public skills @@ -87,15 +86,39 @@ to press a manual CI button or retrigger CI. ## Writing AGENTS.md Files -Every subtree that an agent may work in should have its own `AGENTS.md` with build commands, test commands, code style, and any subtree-specific conventions. Keep each file under 400 lines; split into separate docs or skills when it grows past that. +Every subtree that an agent may work in should have its own `AGENTS.md` with +build commands, test commands, code style, and any subtree-specific conventions. +Keep each file under 400 lines. Split long examples or workflow detail into +separate docs or skills. -`AGENTS.md` is the source of truth for agent guidance. Cursor and Codex read `AGENTS.md` directly. Claude Code reads `CLAUDE.md`, so every directory that has an `AGENTS.md` also has a sibling `CLAUDE.md` that is a regular file containing the single line `@AGENTS.md`. That import line tells Claude Code to load the adjacent `AGENTS.md`, so all three tools end up on the same content. When creating a new `AGENTS.md`, create the companion `CLAUDE.md` in the same commit: `printf '@AGENTS.md\n' > CLAUDE.md`. Do not use a symlink, and never put unique content in `CLAUDE.md`. +Apply `documentation-style` whenever you create or edit `AGENTS.md` or +`CLAUDE.md`. Keep the guidance short, public-safe, and command-focused. + +`AGENTS.md` is the source of truth for agent guidance. Cursor and Codex read it +directly. + +Claude Code reads `CLAUDE.md`. Every directory with an `AGENTS.md` also has a +sibling `CLAUDE.md` containing only `@AGENTS.md`. That import line tells Claude +Code to load the adjacent `AGENTS.md`, so all three tools use the same content. + +When creating a new `AGENTS.md`, create the companion `CLAUDE.md` in the same +commit: `printf '@AGENTS.md\n' > CLAUDE.md`. Do not use a symlink, and never put +unique content in `CLAUDE.md`. ## Skills -Skills are reusable, on-demand agent instructions for specific workflows. They follow the [Agent Skills specification](https://agentskills.io/specification) and are compatible with the [Vercel Skills CLI](https://github.com/vercel-labs/skills). Skills are invoked when relevant, not auto-applied (auto-applied guidance belongs in rules, not skills). +Skills are reusable, on-demand agent instructions for specific workflows. They +follow the [Agent Skills specification](https://agentskills.io/specification) +and are compatible with the [Vercel Skills CLI](https://github.com/vercel-labs/skills). + +Skills are invoked when relevant, not auto-applied. Auto-applied guidance +belongs in rules, not skills. -Keep durable skills focused on current behavior, stable prerequisites, and reusable workflows. Do not put in-progress Merge Request/Pull Request tables, merge-order checklists, branch-specific references, or temporary cross-repo coordination status in skills. Put that information in Merge Request/Pull Request descriptions, comments on the ticket, or temporary runbooks instead. +Keep durable skills focused on current behavior, stable prerequisites, and +reusable workflows. Do not put in-progress Pull Request tables, merge-order +checklists, branch-specific references, or temporary cross-repo coordination +status in skills. Put that information in Pull Request descriptions, comments +on the ticket, or temporary runbooks instead. ### Skill structure @@ -151,7 +174,9 @@ fanout directories (`.cursor/skills/`, `.codex/skills/`, `.claude/skills/`) must contain symlinks only, never source skill directories or regular skill files. -The project hook `.cursor/hooks/validate-skill-fanout.py` audits this before an agent finishes. If it reports a fanout error, fix the symlinks or source placement before responding. +The project hook `.cursor/hooks/validate-skill-fanout.py` audits this before an +agent finishes. If it reports a fanout error, fix the symlinks or source +placement before responding. When adding a skill: 1. Decide visibility (public or private) and audience (`user/skills` or `dev/skills`). @@ -163,7 +188,7 @@ When adding a skill: When editing source files under `ai-tooling/user/skills/nvcf-self-managed-cli/**` or `ai-tooling/user/skills/nvcf-self-managed-installation/**`, regenerate the embedded CLI -data and commit the result in the same MR: +data and commit the result in the same Pull Request: ```sh cd src/clis/nvcf-cli @@ -179,15 +204,15 @@ is stale. Do not edit this file by hand. Hooks follow the same source-and-fanout pattern as root dev skills. Implementation scripts live in `ai-tooling/dev/hooks/`; `.cursor/hooks/`, `.codex/hooks/`, and `.claude/hooks/` are symlink fanouts only. Tool-specific -hook configs may be regular files. Internal-only stop hooks and private -snapshot hygiene checks live outside this public snapshot; still follow OSS -Snapshot Hygiene manually before finishing. +hook config files outside those fanout directories may be regular files. +Internal-only stop hooks and private snapshot hygiene checks live outside this +public snapshot; still follow OSS Snapshot Hygiene manually before finishing. ### Public skills | Skill | Location | Purpose | |-------|----------|---------| -| `documentation-style` | `ai-tooling/dev/skills/` | NVCF documentation conventions (no bold, no emojis, no em-dash) | +| `documentation-style` | `ai-tooling/dev/skills/` | Public docs, AGENTS, and skill-writing style | | `nvcf-explore-stack` | `ai-tooling/dev/skills/` | Navigate the self-hosted stack topology and dependency graph | | `nvcf-self-managed-cli` | `ai-tooling/user/skills/` | Install, operate, and manage self-managed NVCF through `nvcf-cli` | | `nvcf-self-managed-installation` | `ai-tooling/user/skills/` | Install and deploy the self-managed NVCF stack | @@ -230,11 +255,11 @@ Foundational types (not in release notes): `docs`, `build`, `test`, `refactor`, When a commit adds or updates a third-party dependency, call out the dependency name and version in the body so reviewers can assess license and security impact. -## Merge Requests/Pull Requests +## Pull Requests -Use Conventional Commit format for Merge Request/Pull Request titles, as -described in the Commit Messages section. Release automation depends on this -format. Examples: `feat:`, `fix:`, `chore:`, `docs:`. +Use Conventional Commit format for Pull Request titles, as described in the +Commit Messages section. Release automation depends on this format. Examples: +`feat:`, `fix:`, `chore:`, `docs:`. For GitHub PRs, agents must create or link a public `NVIDIA/nvcf` issue in `## Issues` using `Closes #123`, `Fixes #123`, `Resolves NVIDIA/nvcf#123`, or @@ -242,17 +267,19 @@ For GitHub PRs, agents must create or link a public `NVIDIA/nvcf` issue in use `NO-REF`, Jira keys, private tracker or bug IDs, private URLs, title-only refs, other-repo issues, or invented issue numbers for agent-authored PRs. -Use a structured Merge Request/Pull Request description. Subtree repos may define -their own Merge Request/Pull Request template; fall back to this shape when none -exists. Do not include a test plan checklist unless explicitly requested. +Use a structured Pull Request description. Start from the root Pull Request +template. Fall back to this shape only when that template is unavailable. Do +not include a test plan checklist unless explicitly requested. -Every Merge Request/Pull Request description must explain why the change is -needed, not only what changed. Include enough context that a reviewer can -understand the motivation without doing detective work. Always include: +Every Pull Request description must explain why the change is needed, not only +what changed. Include enough context that a reviewer can understand the +motivation without doing detective work. Always include: - the problem, requirement, review comment, or CI blocker driving the change - what changed and how the changed pieces connect -- links to upstream Merge Requests/Pull Requests, tickets, bugs, or related - reviews when relevant +- links to upstream Pull Requests, tickets, bugs, or related reviews when + relevant +- tests run, skipped tests, and whether QA is needed +- dependency changes, license review status, and NOTICE impact ``` ## Why @@ -279,7 +306,7 @@ understand the motivation without doing detective work. Always include: ## References -## Related Merge Requests/Pull Requests +## Related Pull Requests ## Dependencies @@ -288,11 +315,18 @@ understand the motivation without doing detective work. Always include: ## Cross-subtree impact -NVCF clients in this repo (notably `src/clis/nvcf-cli`) are hand-written against control-plane and invocation-plane APIs. When changing public API surfaces (request/response shapes, auth flow, new endpoints, removed fields), evaluate whether `src/clis/nvcf-cli` needs a matching change, and list affected clients in the Merge Request/Pull Request "Related Merge Requests/Pull Requests" section. If the CLI needs an update, file a follow-up issue. +NVCF clients in this repo (notably `src/clis/nvcf-cli`) are hand-written against +control-plane and invocation-plane APIs. When changing public API surfaces +(request/response shapes, auth flow, new endpoints, removed fields), evaluate +whether `src/clis/nvcf-cli` needs a matching change, and list affected clients +in the Pull Request "Related Pull Requests" section. If the CLI needs an +update, file a follow-up issue. ## Tests -Code changes must include tests. If a change does not include tests, explain why in the Merge Request/Pull Request description (for example: pure documentation, CI-only change, or refactor with full existing coverage). +Code changes must include tests. If a change does not include tests, explain why +in the Pull Request description (for example: pure documentation, CI-only +change, or refactor with full existing coverage). Prefer the repo-native test runner (`make test`, `go test`, `cargo test`, etc.). Run tests before committing. Check coverage requirements in the subtree `AGENTS.md` or CI config. @@ -300,7 +334,9 @@ Prefer the repo-native test runner (`make test`, `go test`, `cargo test`, etc.). Write self-documenting code. Add comments only when the logic is non-obvious. Match the existing package structure, naming, and error-handling conventions of each subtree instead of imposing a new framework. -Follow the documentation style rules in `.cursor/skills/documentation-style/SKILL.md`: +Follow the documentation style rules in `.codex/skills/documentation-style/SKILL.md` +(same source as `.cursor/skills/documentation-style/SKILL.md` and +`.claude/skills/documentation-style/SKILL.md`): - No markdown bold for emphasis. - No emojis. - No em-dash (U+2014). @@ -381,7 +417,8 @@ When a change affects observability, verify: - New spans propagate context and set error attributes on failure. - New metrics follow the naming convention and are pre-initialized. - Existing dashboards and alerts are not broken by renamed or removed metrics/spans. -- The Merge Request/Pull Request description calls out the observability impact if dashboards or alerts may need updating. +- The Pull Request description calls out the observability impact if dashboards + or alerts may need updating. ## Diagrams @@ -389,4 +426,5 @@ When a change modifies runtime behavior, data flow, or component interactions, a ## Issue Tracking -Reference related issues in commits and Merge Request/Pull Request descriptions. When creating follow-up work, file a ticket rather than leaving a TODO in code. +Reference related issues in commits and Pull Request descriptions. When +creating follow-up work, file a ticket rather than leaving a TODO in code. diff --git a/ai-tooling/README.md b/ai-tooling/README.md index 88f70bf33..f3d19517f 100644 --- a/ai-tooling/README.md +++ b/ai-tooling/README.md @@ -6,7 +6,7 @@ Public agent skills for users and developers working with NVIDIA Cloud Functions | Skill | Description | |-------|-------------| -| [documentation-style](dev/skills/documentation-style/SKILL.md) | NVCF documentation conventions for public repo prose | +| [documentation-style](dev/skills/documentation-style/SKILL.md) | Public docs, AGENTS, and skill-writing style | | [nvcf-explore-stack](dev/skills/nvcf-explore-stack/SKILL.md) | Navigate the self-hosted stack topology, helmfile dependency graph, chart ownership, and deployment order | | [nvcf-self-managed-installation](user/skills/nvcf-self-managed-installation/SKILL.md) | Install and deploy the nvcf-self-managed-stack helmfile bundle: installation, teardown, values overrides, pull secrets, debugging | | [nvcf-self-managed-cli](user/skills/nvcf-self-managed-cli/SKILL.md) | Standalone NVCF CLI (`nvcf-cli`) for self-managed/self-hosted deployments: install, status, add compute plane, teardown, function lifecycle, invocation, and API keys | diff --git a/ai-tooling/dev/skills/documentation-style/SKILL.md b/ai-tooling/dev/skills/documentation-style/SKILL.md index 726e105e3..4f434cdad 100644 --- a/ai-tooling/dev/skills/documentation-style/SKILL.md +++ b/ai-tooling/dev/skills/documentation-style/SKILL.md @@ -1,8 +1,9 @@ --- name: documentation-style description: >- - NVCF docs style: no bold, no emojis, no em-dash or en-dash, ASCII-only prose. - Use when editing markdown, READMEs, AGENTS.md, plans, or PR descriptions. + NVCF public docs style: short, plain, ASCII Markdown with no bold, emojis, + em-dash, or en-dash. Use when editing public docs, READMEs, AGENTS.md, agent + skills, plans, GitHub issues, or GitHub Pull Request descriptions. license: Apache-2.0 compatibility: Requires an NVCF documentation or repository checkout author: "nvcf-core-eng " @@ -34,40 +35,68 @@ metadata: ## Purpose -Keep NVCF documentation plain, consistent, and agent-friendly. Avoid typographic Unicode that breaks grep and diff tools, and avoid emphasis patterns that encourage noisy, marketing-flavored prose. +Keep NVCF documentation plain, consistent, and useful for external readers. +Write short docs an agent or contributor can act on without private context. +Avoid typographic Unicode that breaks grep and diff tools, and avoid emphasis +patterns that make docs noisy. ## When to use -- Any new or edited markdown in this repo (root docs, `dependencies-plan.md`, skills, comments in guides). -- User-facing explanations, commit messages, or PR bodies when the user wants repo style. -- Refactors of existing docs where you are already changing the file. +- Any new or edited public Markdown in this repo. +- `AGENTS.md`, `CLAUDE.md`, `SKILL.md`, READMEs, plans, and guides. +- GitHub issue bodies, commit messages, and Pull Request descriptions. +- Existing docs you are changing for another reason. ## Instructions -1. No markdown bold for emphasis. Do not use `**...**` or `__...__`, and do not reach for raw HTML `` or ``. Use structure (headings, lists, tables) and `backticks` for paths, commands, env vars, and identifiers. Let the wording carry emphasis. +1. No markdown bold for emphasis. Do not use `**...**`, `__...__`, raw HTML +``, or ``. Use headings, lists, and `backticks` for paths, commands, +env vars, and identifiers. 2. No emojis in documentation or user-facing prose. -3. No em-dash (Unicode U+2014) or en-dash (U+2013). Split the thought into two sentences, or use a comma, parenthesis, or colon when you need a break. +3. No em-dash (Unicode U+2014) or en-dash (U+2013). Split the thought into two +sentences, or use a comma, semicolon, parenthesis, or colon. -4. ASCII only in committed prose. Avoid smart quotes, ellipsis characters, non-breaking spaces, arrows, and other typographic Unicode. Prefer `->` over an arrow glyph and `...` over a single-character ellipsis. Code blocks and quoted fixtures are exempt. +4. ASCII only in committed prose. Avoid smart quotes, ellipsis characters, +non-breaking spaces, arrows, and other typographic Unicode. Prefer `->` over an +arrow glyph and `...` over a single-character ellipsis. Code blocks and quoted +fixtures are exempt. -5. Be succinct. Prefer short sentences and direct wording. Cut filler and repetition. Keep one idea per sentence when possible. +5. Be succinct. Prefer short sentences and direct wording. Cut filler and +repetition. Keep one idea per sentence when possible. -6. Be easy to understand. Define acronyms on first use if the audience is broad. Prefer concrete examples over abstract jargon. +6. Prefer lists for short, scan-friendly structure. Use bullets for unordered +items and numbered lists when sequence, priority, or stable rule references +matter. Use tables only when columns make comparison, status, option tradeoffs, +or matrix decisions easier. Do not turn a short list into a table. + +7. Be easy to understand. Define acronyms on first use if the audience is broad. +Prefer concrete examples over abstract jargon. + +8. Write for GitHub readers. Use public names, public paths, and public +behavior. Replace private evidence with the user-visible reason for the change. + +9. Keep agent guidance actionable. Say when to use a skill, what to inspect +first, what command to run, and what done means. Do not add temporary branch +status, Pull Request queues, merge-order notes, or private routing details. + +10. Avoid vague agent language. Remove filler such as "ensure", "leverage", +"robust", "comprehensive", "where applicable", and "as needed" unless the term +adds a concrete condition. ## Examples Inline bold label, replaced with a plain prefix: -``` +```text Before: **Note:** restart after edit. After: Note: restart after edit. ``` Bold section header, replaced with a real heading: -``` +```text Before: **Prerequisites** - Repository access to github.com/NVIDIA/nvcf. @@ -77,25 +106,40 @@ After: ## Prerequisites - Repository access to github.com/NVIDIA/nvcf. ``` -Em-dash, replaced with a period: +Double hyphen used as a dash, replaced with a period: -``` +```text Before: Services live upstream -- this repo mirrors them. After: Services live upstream. This repo mirrors them. ``` +Long agent guidance, replaced with commands and durable criteria: + +```text +Before: Ensure agents comprehensively verify symlink fanout where applicable. + +After: Run `python3 ai-tooling/dev/hooks/validate-skill-fanout.py` after + changing root skills. Fix every reported path before finishing. +``` + ## Editing existing files -If a file already uses bold, emojis, em-dashes, en-dashes, or non-ASCII punctuation, normalize it when you touch that file for another reason, or when the user asks for a style pass. Do not expand scope into unrelated trees just to fix style. +If a file already uses bold, emojis, em-dashes, en-dashes, or non-ASCII +punctuation, normalize it when you touch that file for another reason, or when +the user asks for a style pass. Do not expand scope into unrelated trees just to +fix style. ## Limitations - The rules target agent-edited prose in this repo. Upstream documentation keeps its own style until merged natively. -- There is no automated linter today. Enforcement happens during review. +- There is no automated linter for prose today. Review catches style issues. ## Exceptions -- Content you are quoting verbatim (upstream LICENSE text, cited errors, user paste). -- Generated files (for example output from `go run ./tools/collect-dependencies`) where the generator controls formatting; fix style in the generator if needed. -- Auto-generated changelogs or release notes assembled from external commit messages; fix the source commits, not the rolled-up file. +- Content you are quoting verbatim, such as upstream LICENSE text, cited errors, + or user paste. +- Generated files where the generator controls formatting. Fix style in the + generator if needed. +- Auto-generated changelogs or release notes assembled from external commit + messages. Fix the source commits, not the rolled-up file.