chore(docs): add agent tooling guidelines#93
Open
coryrylan wants to merge 2 commits into
Open
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds interactive internal guideline pages (Agent Tooling, Agent Ownership) with SVG-driven detail panels, inserts an Agent Tooling nav entry, refactors JSON‑LD generation to emit a schema.org ChangesAgent Tooling Documentation and Navigation
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@projects/site/src/docs/internal/guidelines/agent-tooling.md`:
- Around line 39-58: The SVG layer groups (the <g> elements with
data-tooling-layer="metadata", "static-tools", "cli-skills", and "mcp") need
accessibility attributes and keyboard handlers: add role="button", tabindex="0"
and an appropriate aria-label to each <g>, and ensure focus styling is possible;
then update the JS that currently binds only to mouse events (click, mouseenter)
to also listen for keyboard events (keydown) and trigger the same handlers on
Enter and Space so keyboard and screen-reader users can activate the layers.
- Around line 245-248: The four consecutive list items in agent-tooling.md that
all start with "Do not" are repetitive; update the four bullets (“Do not hide
facts in prompts.”, “Do not make MCP the source of truth.”, “Do not ship
model-only validation.”, “Do not return raw dumps.”) to vary sentence openings
while keeping the same prohibitions and intent—for example change one or two to
affirmative guidance or passive constructions (e.g., “Avoid hiding facts in
prompts.”, “Treat MCP as an adapter rather than the source of truth.”, “Ensure
CI-enforceable validation rather than model-only checks.”, “Distill context
before returning dumps.”) so the wording satisfies Vale/Google style and
write-good rules and preserves the original meaning.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 5e8d7d8b-6277-4a3c-a3e8-b0768c081cf0
📒 Files selected for processing (2)
projects/site/src/_11ty/layouts/common.jsprojects/site/src/docs/internal/guidelines/agent-tooling.md
coryrylan
force-pushed
the
topic-tool-guidance
branch
from
c6ada7b to
4f4d1bd
Compare
There was a problem hiding this comment.
♻️ Duplicate comments (2)
projects/site/src/docs/internal/guidelines/agent-tooling.md (2)
245-248:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winVary sentence structure to improve readability.
Four consecutive list items begin with "Do not," which creates repetitive phrasing. As per coding guidelines, documentation files must follow Vale linting rules (Google style guide, write-good rules, and custom Element rules).
📝 Suggested rewording
- **Do not hide facts in prompts.** Prompts are runtime hints, not durable data. -- **Do not make MCP the source of truth.** Treat it as an adapter over services. -- **Do not ship model-only validation.** If CI cannot enforce it, the harness is incomplete. -- **Do not return raw dumps.** Distill context before it reaches the agent. + **Avoid making MCP the source of truth.** Treat it as an adapter over services. + **Ensure CI enforces all validation.** If CI cannot enforce it, the harness is incomplete. + **Distill outputs before returning them.** Never return raw dumps to agents.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@projects/site/src/docs/internal/guidelines/agent-tooling.md` around lines 245 - 248, The four consecutive list items beginning with "Do not" are repetitively phrased and violate the Vale linting/write-good style; revise the four bullets (the items currently reading "Do not hide facts in prompts.", "Do not make MCP the source of truth.", "Do not ship model-only validation.", "Do not return raw dumps.") to vary sentence structure while preserving intent—e.g., convert some to positive or alternative imperatives, combine related points, or rephrase to start with different verbs or noun phrases, ensuring the wording conforms to Google-style and Element lint rules and keeps the original meaning and emphasis.
39-58:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAdd keyboard navigation and ARIA attributes to interactive SVG layers.
The interactive SVG layer groups lack accessibility support:
- No
role="button"ortabindex="0"for keyboard focus- No ARIA labels describing each layer
- JavaScript event listeners (lines 205-215) handle only mouse events (click, mouseenter), not keyboard events (keydown)
Keyboard-only users and screen reader users cannot interact with the diagram. As per coding guidelines, documentation must follow accessibility best practices.
♿ Recommended accessibility fixes
Add accessibility attributes to each
<g>element:- <g data-tooling-layer="metadata" style="cursor:pointer"> + <g data-tooling-layer="metadata" role="button" tabindex="0" aria-label="Metadata layer - Source of Truth" style="cursor:pointer">Apply similar changes to all layer groups (static-tools, cli-skills, mcp).
Then update the JavaScript to handle keyboard events:
layerGroups.forEach(group => { group.addEventListener('click', () => { locked = true; setToolingLayer(group.getAttribute('data-tooling-layer')); }); + group.addEventListener('keydown', (e) => { + if (e.key === 'Enter' || e.key === ' ') { + e.preventDefault(); + locked = true; + setToolingLayer(group.getAttribute('data-tooling-layer')); + } + }); group.addEventListener('mouseenter', () => { if (!locked) { setToolingLayer(group.getAttribute('data-tooling-layer')); } }); });Also applies to: 205-215
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@projects/site/src/docs/internal/guidelines/agent-tooling.md` around lines 39 - 58, The SVG layer groups (e.g., elements with data-tooling-layer="metadata", "static-tools", "cli-skills", "mcp") are not keyboard- or screen-reader accessible; add role="button", tabindex="0", and an appropriate aria-label (e.g., aria-label="Metadata layer") to each <g> to make them focusable and identifiable, and update the event handling in the script that attaches listeners to these groups (the code that currently listens for click and mouseenter) to also handle keyboard activation (keydown/keyup or keypress) for Enter and Space so keyboard users can activate and hover-equivalent focus styles; ensure the same ARIA and keyboard handling is applied consistently to all tooling-layer groups referenced by data-tooling-layer attributes.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Duplicate comments:
In `@projects/site/src/docs/internal/guidelines/agent-tooling.md`:
- Around line 245-248: The four consecutive list items beginning with "Do not"
are repetitively phrased and violate the Vale linting/write-good style; revise
the four bullets (the items currently reading "Do not hide facts in prompts.",
"Do not make MCP the source of truth.", "Do not ship model-only validation.",
"Do not return raw dumps.") to vary sentence structure while preserving
intent—e.g., convert some to positive or alternative imperatives, combine
related points, or rephrase to start with different verbs or noun phrases,
ensuring the wording conforms to Google-style and Element lint rules and keeps
the original meaning and emphasis.
- Around line 39-58: The SVG layer groups (e.g., elements with
data-tooling-layer="metadata", "static-tools", "cli-skills", "mcp") are not
keyboard- or screen-reader accessible; add role="button", tabindex="0", and an
appropriate aria-label (e.g., aria-label="Metadata layer") to each <g> to make
them focusable and identifiable, and update the event handling in the script
that attaches listeners to these groups (the code that currently listens for
click and mouseenter) to also handle keyboard activation (keydown/keyup or
keypress) for Enter and Space so keyboard users can activate and
hover-equivalent focus styles; ensure the same ARIA and keyboard handling is
applied consistently to all tooling-layer groups referenced by
data-tooling-layer attributes.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: f16af1cb-568c-4557-9959-db8f51747ca5
📒 Files selected for processing (2)
projects/site/src/_11ty/layouts/common.jsprojects/site/src/docs/internal/guidelines/agent-tooling.md
There was a problem hiding this comment.
Actionable comments posted: 4
♻️ Duplicate comments (2)
projects/site/src/docs/internal/guidelines/agent-tooling.md (2)
39-58:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAdd keyboard and ARIA support for interactive SVG layers.
These layer controls are mouse-only and not exposed as interactive elements for keyboard/screen-reader users, which blocks accessible interaction.
♿ Suggested patch
- <g data-tooling-layer="metadata" style="cursor:pointer"> + <g data-tooling-layer="metadata" role="button" tabindex="0" aria-label="Metadata layer: Source of truth" style="cursor:pointer"> ... - <g data-tooling-layer="static-tools" style="cursor:pointer"> + <g data-tooling-layer="static-tools" role="button" tabindex="0" aria-label="Static tools layer: Deterministic rejection" style="cursor:pointer"> ... - <g data-tooling-layer="cli-skills" style="cursor:pointer"> + <g data-tooling-layer="cli-skills" role="button" tabindex="0" aria-label="CLI and skills layer: Commands and workflow context" style="cursor:pointer"> ... - <g data-tooling-layer="mcp" style="cursor:pointer"> + <g data-tooling-layer="mcp" role="button" tabindex="0" aria-label="MCP and apps layer: Agent interfaces" style="cursor:pointer"> ... layerGroups.forEach(group => { group.addEventListener('click', () => { locked = true; setToolingLayer(group.getAttribute('data-tooling-layer')); }); + group.addEventListener('keydown', event => { + if (event.key === 'Enter' || event.key === ' ') { + event.preventDefault(); + locked = true; + setToolingLayer(group.getAttribute('data-tooling-layer')); + } + }); group.addEventListener('mouseenter', () => { if (!locked) { setToolingLayer(group.getAttribute('data-tooling-layer')); } }); });Also applies to: 205-215
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@projects/site/src/docs/internal/guidelines/agent-tooling.md` around lines 39 - 58, The SVG group elements with data-tooling-layer attributes (e.g., data-tooling-layer="metadata", "static-tools", "cli-skills", "mcp") are mouse-only and need ARIA/keyboard support: make each <g> focusable (tabindex="0"), add an appropriate role (role="button") and an accessible name (aria-label or aria-labelledby reflecting the visible text), expose pressed/state if relevant (aria-pressed or aria-current), and wire keyboard handlers so Enter/Space activate the same handler as click; ensure any color-only information also has text alternatives and test with a screen reader/keyboard to confirm focus order and activation match the existing click behavior.
245-248:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winReduce repetitive “Do not …” sentence starts in this bullet cluster.
This block is likely to trip Vale/write-good repetition checks; vary openings while keeping the same prohibitions.
As per coding guidelines, documentation files “must follow Vale linting rules (Google style guide, write-good rules, and custom Element rules) and include accepted technical terms from
/config/vale/styles/config/vocabularies/Elements/accept.txt.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@projects/site/src/docs/internal/guidelines/agent-tooling.md` around lines 245 - 248, Rewrite the four bullets that start with "Do not…" so their prohibitive intent remains but the sentence openings vary to avoid repetition and satisfy Vale/write-good rules; update the lines referencing "Do not hide facts in prompts.", "Do not make MCP the source of truth.", "Do not ship model-only validation.", and "Do not return raw dumps." into varied forms (e.g., "Avoid hiding facts in prompts.", "Treat MCP as an adapter, not the source of truth.", "Ensure validation isn't model-only; CI must be able to enforce it.", "Distill context rather than returning raw dumps.") while keeping the same meaning and accepted technical terms from the project's vocabulary.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@projects/site/package.json`:
- Around line 193-203: Remove the unnecessary Wireit dependency from the test
task by deleting the "dependencies": ["build:dependencies"] property inside the
"test" Wireit task in package.json (the object named "test" that runs "vitest
run src/_11ty/layouts/metadata.test.js"); ensure the rest of the "test" task
(command, files, output) remains unchanged so the test runs without building
workspace packages.
In `@projects/site/src/_11ty/layouts/metadata.js`:
- Around line 195-202: The current block sets article.programmingModel and
article.targetPlatform for any isApiReference pages
(isApiReference/isApiReferencePage), which incorrectly marks non-component docs;
change the guard to only apply for actual component pages by checking the
element object (e.g., element?.tagName or another component-specific property)
in addition to isApiReference — e.g. replace the if (isApiReference) around the
block with if (isApiReference && element?.tagName) (and keep
article.assemblyVersion = element.version only when element?.version exists) so
programmingModel/targetPlatform are only set for real component pages.
In `@projects/site/src/_11ty/layouts/metadata.test.js`:
- Around line 37-136: Add a regression test that exercises a non-component
APIReference route (e.g. CLI/integration/lint/MCP) by calling
getGraph(renderJsonLd flow) with createData that does NOT include a component
tag (use content with a code block like the existing CLI example) and
createMeta('/docs/cli/'), then locate the APIReference node via findNode(graph,
'APIReference') and assert it does NOT have component-specific properties
(expect(article).not.toHaveProperty('programmingModel') and
expect(article).not.toHaveProperty('assemblyVersion')); place this alongside the
other renderJsonLd tests so it covers the non-component branch.
In `@projects/site/src/docs/internal/guidelines/agent-ownership.md`:
- Around line 29-57: The stage nodes (e.g., g[data-ownership-layer="intent"],
"draft", "edit", "gates", "review") are only mouse-interactive—make them
keyboard- and screen-reader-accessible by adding interactive semantics
(role="button"), keyboard focusability (tabindex="0"), clear accessible names
(aria-label or aria-labelledby pointing to the visible <text>), and keyboard
event handling for Enter/Space activation that mirrors the click handler; ensure
visible focus styles and that the same changes are applied to the other
identical group at lines referenced (the other g[data-ownership-layer] block).
---
Duplicate comments:
In `@projects/site/src/docs/internal/guidelines/agent-tooling.md`:
- Around line 39-58: The SVG group elements with data-tooling-layer attributes
(e.g., data-tooling-layer="metadata", "static-tools", "cli-skills", "mcp") are
mouse-only and need ARIA/keyboard support: make each <g> focusable
(tabindex="0"), add an appropriate role (role="button") and an accessible name
(aria-label or aria-labelledby reflecting the visible text), expose
pressed/state if relevant (aria-pressed or aria-current), and wire keyboard
handlers so Enter/Space activate the same handler as click; ensure any
color-only information also has text alternatives and test with a screen
reader/keyboard to confirm focus order and activation match the existing click
behavior.
- Around line 245-248: Rewrite the four bullets that start with "Do not…" so
their prohibitive intent remains but the sentence openings vary to avoid
repetition and satisfy Vale/write-good rules; update the lines referencing "Do
not hide facts in prompts.", "Do not make MCP the source of truth.", "Do not
ship model-only validation.", and "Do not return raw dumps." into varied forms
(e.g., "Avoid hiding facts in prompts.", "Treat MCP as an adapter, not the
source of truth.", "Ensure validation isn't model-only; CI must be able to
enforce it.", "Distill context rather than returning raw dumps.") while keeping
the same meaning and accepted technical terms from the project's vocabulary.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 10133a05-8509-4d69-90c7-e18cde886f03
📒 Files selected for processing (6)
projects/site/package.jsonprojects/site/src/_11ty/layouts/common.jsprojects/site/src/_11ty/layouts/metadata.jsprojects/site/src/_11ty/layouts/metadata.test.jsprojects/site/src/docs/internal/guidelines/agent-ownership.mdprojects/site/src/docs/internal/guidelines/agent-tooling.md
coryrylan
force-pushed
the
topic-tool-guidance
branch
from
f489f85 to
b6364f2
Compare
coryrylan
commented
May 19, 2026
| function getContentDates(data) { | ||
| return { | ||
| datePublished: normalizeDate(data.datePublished ?? data.published ?? data.git?.created ?? data.git?.createdTime), | ||
| dateModified: normalizeDate(data.dateModified ?? data.modified ?? data.git?.modified ?? data.git?.modifiedTime) |
Collaborator
Author
There was a problem hiding this comment.
Adjust so each build is not creating a new dateModified entry
coryrylan
commented
May 19, 2026
| codeSampleType: getCodeSampleType(data, meta), | ||
| programmingLanguage: programmingLanguage.length === 1 ? programmingLanguage[0] : programmingLanguage, | ||
| runtimePlatform: getRuntimePlatform(meta), | ||
| targetProduct: { '@id': SOFTWARE_ID } |
Collaborator
Author
There was a problem hiding this comment.
Detect and signal source code metadata/structured schema
coryrylan
commented
May 19, 2026
|
|
||
| if (isApiReference && element?.manifest?.tagName) { | ||
| article.programmingModel = 'Web Components'; | ||
| article.targetPlatform = 'Web'; |
Collaborator
Author
There was a problem hiding this comment.
Provide more accurate schema data for what the api doc is describing
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (3)
projects/site/src/docs/internal/guidelines/agent-ownership.md (1)
29-57:⚠️ Potential issue | 🟠 Major | ⚡ Quick winMake ownership rail stages keyboard- and screen-reader-accessible.
The stage nodes are interactive controls but lack keyboard navigation and ARIA attributes. They have no
role,tabindex, or accessible labels, and the JavaScript only handles mouse events.♿ Suggested accessibility fixes
Add accessibility attributes to each
<g>element:- <g data-ownership-layer="intent" style="cursor:pointer"> + <g data-ownership-layer="intent" role="button" tabindex="0" aria-label="Intent stage - Engineer Framing" style="cursor:pointer">Apply to all stage groups (intent, draft, edit, gates, review). Then update the JavaScript to handle keyboard events:
layerGroups.forEach(group => { group.addEventListener('click', () => { locked = true; setOwnershipStage(group.getAttribute('data-ownership-layer')); }); + group.addEventListener('keydown', (e) => { + if (e.key === 'Enter' || e.key === ' ') { + e.preventDefault(); + locked = true; + setOwnershipStage(group.getAttribute('data-ownership-layer')); + } + }); group.addEventListener('mouseenter', () => { if (!locked) { setOwnershipStage(group.getAttribute('data-ownership-layer')); } }); });🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@projects/site/src/docs/internal/guidelines/agent-ownership.md` around lines 29 - 57, The ownership stage <g> nodes (elements with data-ownership-layer="intent|draft|edit|gates|review") are not keyboard- or screen-reader-accessible; add role="button", tabindex="0", and a descriptive aria-label (e.g., "Intent stage: Engineer Framing") to each <g>, and apply visible focus styling; then update the existing JS event handling for these same data-ownership-layer nodes to listen for keydown and treat Enter/Space the same as click (invoke the existing mouse handler), ensure focus is moved/managed appropriately when stages are activated, and keep pointer/mouse handlers intact so both mouse and keyboard users trigger identical behavior.projects/site/src/docs/internal/guidelines/agent-tooling.md (2)
245-248:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winVary sentence structure to improve readability.
Four consecutive bullets begin with "Do not," which Vale linting tools flag as repetitive. Consider varying the phrasing while preserving the guidance. As per coding guidelines, documentation files must follow Vale linting rules (Google style guide, write-good rules, and custom Element rules).
📝 Suggested rewording
- **Do not hide facts in prompts.** Prompts are runtime hints, not durable data. -- **Do not make MCP the source of truth.** Treat it as an adapter over services. -- **Do not ship model-only validation.** If CI cannot enforce it, the harness is incomplete. -- **Do not return raw dumps.** Distill context before it reaches the agent. + **Avoid making MCP the source of truth.** Treat it as an adapter over services. + **Ensure CI enforces all validation.** If CI cannot enforce it, the harness is incomplete. + **Distill outputs before returning them.** Never return raw dumps to agents.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@projects/site/src/docs/internal/guidelines/agent-tooling.md` around lines 245 - 248, Rephrase the four consecutive bullets ("Do not hide facts in prompts", "Do not make MCP the source of truth", "Do not ship model-only validation", "Do not return raw dumps") so they no longer all start with "Do not" while preserving their meaning and tone and satisfying Vale linting (Google style/write-good/Element rules); e.g., convert one or two to positive phrasing or action-focused imperatives, vary sentence openings and rhythm, and keep each item concise and directive so the guidance in the existing lines (about prompts, MCP, CI-enforceable validation, and distilling context) remains unchanged.
39-58:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAdd keyboard navigation and ARIA attributes to interactive SVG layers.
The interactive layer groups lack accessibility support - they have no
role,tabindex, or ARIA labels, and the JavaScript only handles mouse events. Keyboard-only and screen reader users cannot interact with the diagram.♿ Recommended accessibility fixes
Add accessibility attributes to each
<g>element:- <g data-tooling-layer="metadata" style="cursor:pointer"> + <g data-tooling-layer="metadata" role="button" tabindex="0" aria-label="Metadata layer - Source of Truth" style="cursor:pointer">Apply similar changes to all layer groups (static-tools, cli-skills, mcp). Then update the JavaScript to handle keyboard events:
layerGroups.forEach(group => { group.addEventListener('click', () => { locked = true; setToolingLayer(group.getAttribute('data-tooling-layer')); }); + group.addEventListener('keydown', (e) => { + if (e.key === 'Enter' || e.key === ' ') { + e.preventDefault(); + locked = true; + setToolingLayer(group.getAttribute('data-tooling-layer')); + } + }); group.addEventListener('mouseenter', () => { if (!locked) { setToolingLayer(group.getAttribute('data-tooling-layer')); } }); });🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@projects/site/src/docs/internal/guidelines/agent-tooling.md` around lines 39 - 58, Add keyboard and screen-reader accessibility to the interactive SVG layer groups by giving each <g> with data-tooling-layer (e.g., "metadata", "static-tools", "cli-skills", "mcp") proper ARIA and focusability attributes (role="button", tabindex="0", and a descriptive aria-label), and update the existing mouse-only event handlers on those <g> elements to also handle keyboard activation (listen for Enter and Space in the same handler or a shared keydown handler) and focus/blur for visible focus styling; ensure any stateful behavior exposed by the handlers also exposes appropriate ARIA state (e.g., aria-pressed or aria-expanded) so screen readers receive the same information as mouse users.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@projects/site/package.json`:
- Around line 195-198: The wireit.test.files array currently only lists
"src/_11ty/layouts/metadata.js" and "src/_11ty/layouts/metadata.test.js" so
changes in dependencies imported by metadata.js are not tracked; update the
package.json wireit.test.files entry for the test target to also include the
imported modules "src/_11ty/utils/env.js" and "src/index.11tydata.js" so Wireit
sees changes to these symbols (metadata.js imports env.js and index.11tydata.js)
and invalidates the cache appropriately.
In `@projects/site/src/docs/internal/guidelines/agent-ownership.md`:
- Around line 265-270: The six consecutive bullets under the agent-ownership
guidance all start with "Do not," which Vale flags as repetitive; revise those
bullet lines (the items beginning "Do not ship prompts.", "Do not accept
generated architecture blindly.", "Do not hide behind the model.", "Do not merge
code nobody can explain.", "Do not rely on style review.", and "Do not normalize
flakes.") to vary sentence openings while preserving meaning and force—for
example, convert some into positive imperatives or restructure them to start
with different verbs or phrases (e.g., "Avoid shipping prompts.", "Treat
generated architecture skeptically.", "Engineers must own changes rather than
the model.", "Reject code that cannot be explained.", "Prioritize behavioral and
architectural risk over style review.", "Fix flaky gates instead of accepting
them."); keep the guidance content and tone intact and ensure the revised lines
pass Vale lint rules.
---
Duplicate comments:
In `@projects/site/src/docs/internal/guidelines/agent-ownership.md`:
- Around line 29-57: The ownership stage <g> nodes (elements with
data-ownership-layer="intent|draft|edit|gates|review") are not keyboard- or
screen-reader-accessible; add role="button", tabindex="0", and a descriptive
aria-label (e.g., "Intent stage: Engineer Framing") to each <g>, and apply
visible focus styling; then update the existing JS event handling for these same
data-ownership-layer nodes to listen for keydown and treat Enter/Space the same
as click (invoke the existing mouse handler), ensure focus is moved/managed
appropriately when stages are activated, and keep pointer/mouse handlers intact
so both mouse and keyboard users trigger identical behavior.
In `@projects/site/src/docs/internal/guidelines/agent-tooling.md`:
- Around line 245-248: Rephrase the four consecutive bullets ("Do not hide facts
in prompts", "Do not make MCP the source of truth", "Do not ship model-only
validation", "Do not return raw dumps") so they no longer all start with "Do
not" while preserving their meaning and tone and satisfying Vale linting (Google
style/write-good/Element rules); e.g., convert one or two to positive phrasing
or action-focused imperatives, vary sentence openings and rhythm, and keep each
item concise and directive so the guidance in the existing lines (about prompts,
MCP, CI-enforceable validation, and distilling context) remains unchanged.
- Around line 39-58: Add keyboard and screen-reader accessibility to the
interactive SVG layer groups by giving each <g> with data-tooling-layer (e.g.,
"metadata", "static-tools", "cli-skills", "mcp") proper ARIA and focusability
attributes (role="button", tabindex="0", and a descriptive aria-label), and
update the existing mouse-only event handlers on those <g> elements to also
handle keyboard activation (listen for Enter and Space in the same handler or a
shared keydown handler) and focus/blur for visible focus styling; ensure any
stateful behavior exposed by the handlers also exposes appropriate ARIA state
(e.g., aria-pressed or aria-expanded) so screen readers receive the same
information as mouse users.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: fdc4fb70-a23c-444c-80a7-a8d1db83c2d5
📒 Files selected for processing (6)
projects/site/package.jsonprojects/site/src/_11ty/layouts/common.jsprojects/site/src/_11ty/layouts/metadata.jsprojects/site/src/_11ty/layouts/metadata.test.jsprojects/site/src/docs/internal/guidelines/agent-ownership.mdprojects/site/src/docs/internal/guidelines/agent-tooling.md
Comment on lines
+195
to
+198
| "files": [ | ||
| "src/_11ty/layouts/metadata.js", | ||
| "src/_11ty/layouts/metadata.test.js" | ||
| ], |
There was a problem hiding this comment.
Include imported module dependencies in wireit.test.files.
Line 195-198 only track metadata.js and its test file. metadata.js also imports src/_11ty/utils/env.js and src/index.11tydata.js; without those, Wireit cache invalidation can miss relevant changes.
Suggested patch
"test": {
"command": "vitest run src/_11ty/layouts/metadata.test.js",
"files": [
"src/_11ty/layouts/metadata.js",
- "src/_11ty/layouts/metadata.test.js"
+ "src/_11ty/layouts/metadata.test.js",
+ "src/_11ty/utils/env.js",
+ "src/index.11tydata.js"
],
"output": []
},🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@projects/site/package.json` around lines 195 - 198, The wireit.test.files
array currently only lists "src/_11ty/layouts/metadata.js" and
"src/_11ty/layouts/metadata.test.js" so changes in dependencies imported by
metadata.js are not tracked; update the package.json wireit.test.files entry for
the test target to also include the imported modules "src/_11ty/utils/env.js"
and "src/index.11tydata.js" so Wireit sees changes to these symbols (metadata.js
imports env.js and index.11tydata.js) and invalidates the cache appropriately.
- Introduced a new internal author documentation page for 'Agent Tooling' detailing best practices for designing metadata, static checks, CLI tools, skills, apps, and MCP servers for agents. Signed-off-by: Cory Rylan <crylan@nvidia.com>
coryrylan
force-pushed
the
topic-tool-guidance
branch
from
b6364f2 to
5ead940
Compare
coryrylan
commented
May 19, 2026
| applicationCategory: 'DeveloperApplication', | ||
| operatingSystem: 'Any', | ||
| runtimePlatform: 'Web', | ||
| softwareHelp: SOFTWARE_URL |
Collaborator
Author
There was a problem hiding this comment.
This is the base meta schema to describe most pages
coryrylan
commented
May 19, 2026
| return LANGUAGE_NAMES[language.toLowerCase()] ?? null; | ||
| } | ||
|
|
||
| function getProgrammingLanguages(data) { |
Collaborator
Author
There was a problem hiding this comment.
This is a rudimentary way to detect code fences/blocks to determine what language information can be provided in the schema/metadata
coryrylan
force-pushed
the
topic-tool-guidance
branch
from
5ead940 to
3f6ffd6
Compare
Signed-off-by: Cory Rylan <crylan@nvidia.com>
coryrylan
force-pushed
the
topic-tool-guidance
branch
from
3f6ffd6 to
b4ae6c4
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary by CodeRabbit
Documentation
SEO / Metadata
@graphcontaining article, optional breadcrumb, application, and optional source-code nodes.Tests & Chores