Add Wayfinder and AI tools guidance#953
Conversation
The self-reported "Debug mode" instruction depended on the agent noticing and recalling the integration order from memory, and couldn't verify anything for a response where no skill was invoked. Document a hook that observes actual tool calls instead, safe to leave in place permanently rather than removed after one-time verification.
…uracy Bring the AI integrations section (5 pages) from WIP to a reviewed state: fix structural gaps (missing Prerequisites, buried headings, no verification step), unify agent/editor terminology across pages, apply editorial guidelines (active voice, pronoun clarity, list punctuation), and verify factual claims — Node.js version requirements and Dropins MCP's B2B coverage — against source instead of assuming. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
A citation-only check turned out to be unreliable in live testing — an agent can answer confidently from training data and simply omit a citation, which looks identical to Wayfinder not firing at all. Add a direct follow-up question asking the agent whether it fetched external documentation or answered from its own knowledge; that self-report proved to be the more reliable signal when validated against a real project. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
bdenham
added
feedback
… checks branch content, not redirects)
|
|
||
| Your agent retrieves this file at the start of a session and follows its routing rules for the duration of the conversation. There is no package to install and no configuration file to create. | ||
|
|
||
| <Aside type="note"> |
There was a problem hiding this comment.
This Aside has no title, which means a reader has to read the body to understand what it's about. A title like "Network permissions" would help.
| ``` | ||
|
|
||
|
|
||
| 3. **Add Wayfinder.** Wayfinder routes questions about Commerce Admin, App Builder, or Document Authoring to the right documentation site. See [Wayfinder](/ai/wayfinder/) for details. Add this line to `AGENTS.md` or `CLAUDE.md` at your project root: |
There was a problem hiding this comment.
Step 1 runs aio commerce extensibility tools-setup, which creates AGENTS.md. But a user reading step 3 in isolation won't know to create the file first. One sentence would close the gap: "If AGENTS.md doesn't exist yet, create it at your project root."
There was a problem hiding this comment.
There's also not a need to "add wayfinder" if you cloned the boilerplate. It is already included in the default AGENTS.md as of hlxsites/aem-boilerplate-commerce#1264.
|
|
||
| The last command prompts you to choose a starter kit, your coding agent, and, if needed, a package manager. See [Install the skills](/ai/boilerplate-skills/#install-the-skills) for details. | ||
|
|
||
| 2. **Add the Dropins MCP (Model Context Protocol) server.** Add the following to your editor's MCP config file — for Claude Code, that's `.mcp.json` at your project root. See [Dropins MCP](/ai/dropins-mcp/) for the exact file and format for other editors: |
There was a problem hiding this comment.
The JSON snippet here duplicates content from the dedicated Dropins MCP page, but only partially. It shows the Claude Code/VS Code Copilot format, which will silently break for Cursor users. The step then links to the full page anyway, so the snippet isn't saving anyone a click.
Consider dropping the snippet entirely and just sending readers to the dedicated page:
Add the Dropins MCP server to your editor. See Dropins MCP for the config snippet for your editor, then return here for step 3.
That keeps the walkthrough complete without duplicating content that already has a maintained home.
|
|
||
| Before you install the integrations, make sure you have the following: | ||
|
|
||
| - **Node.js 22 or later** — The highest requirement across all three integrations. |
There was a problem hiding this comment.
Node.js version conflict: the existing dropins-mcp.mdx (unchanged by this PR) says "Node.js 18 or later". A reader who follows the combined walkthrough in index.mdx and then reads the Dropins MCP page directly will see contradicting requirements.
| <Aside type="note" title="Drop-in API accuracy"> | ||
| Four of these skills — researcher, drop-in developer, project manager, and tester — call Dropins MCP tools to verify slots, events, API functions, and configuration against your project's source, not published documentation. Without the [Dropins MCP server](/ai/dropins-mcp/) installed, most checks fall back to local TypeScript definitions. A few, such as generating slot boilerplate, have no fallback. For the underlying APIs, see the [Blocks reference](/boilerplate/blocks-reference/) and [Drop-in components](/dropins/all/introduction/). | ||
|
|
||
| Adding the MCP (Model Context Protocol) server or [Wayfinder](/ai/wayfinder/) doesn't automatically integrate them with this workflow. See [Install the integrations](/ai/#installation-steps), step 4, for the precedence rule. |
There was a problem hiding this comment.
Numbered step references across pages are maintenance risks. If the step order in index.mdx ever changes, this reference silently breaks. Consider linking to a stable anchor (/ai/#coordination-instructions) or rephrasing without the step number.
| import Aside from '@components/Aside.astro'; | ||
| import Link from '@components/Link.astro'; | ||
|
|
||
| <Link href="https://github.com/adobe-commerce/wayfinder" text="Wayfinder" /> is a free, open-source router for AI coding agents. Adobe Commerce documentation is spread across several separate sites, so an agent can easily search the wrong one or answer from outdated training data. Wayfinder reads your question, routes it to the right source, and tells your agent to fetch and cite that source before it answers. |
There was a problem hiding this comment.
Technical nit: Wayfinder is not a running application, it's just context/instructions for an agent.
3 participants
Purpose of this pull request
Restructures the AI docs section around a new Wayfinder page. Renames and rewrites existing AI pages into a clearer sidebar flow ("AI Integrations"), replaces "Build with AI" with a fallback-docs page, and updates redirects for the moved slugs.
Associated JIRA ticket
N/A
Staging preview
N/A
Affected pages
src/content/docs/ai/wayfinder.mdx— newsrc/content/docs/ai/static-text-files.mdx— new, replacesai/build-with-ai.mdxsrc/content/docs/ai/boilerplate-skills.mdx— new, replacesai/ai-agent-skills.mdxsrc/content/docs/ai/index.mdx— rewritten as the combined installation walkthroughsrc/content/docs/boilerplate/index.mdx— link update after theboilerplate-skillsrenameastro.sidebar.mjs— AI section relabeled and reorderedastro.redirects.mjs— redirects added for the two renamed pagesLinks to source code
N/A
Summary
ai-agent-skills.mdx→boilerplate-skills.mdxandbuild-with-ai.mdx→static-text-files.mdx, updating the one inbound link onboilerplate/index.mdx.index.mdxas a single walkthrough covering all three integrations (boilerplate skills, Dropins MCP, Wayfinder).Testing
Ran a full local build (
npm run build) to confirmstarlight-links-validatorpasses with no broken links, and reviewed the updated content for clarity, structure, and internal links.