feat(duplo-extension-dev): file extensions under a root-level agent

[aboutte]

Summary

When an author builds an extension, the extension skills now ask which agent it should be filed under. The answer is written as an optional agent field at the root of the manifest, next to id, name and version:

"agent": "Release Management"
// or, to suggest where the agent's heading sits in the left nav:
"agent": { "name": "Release Management", "order": 3 }

• Starter list: DevOps, Compliance, Observability, Release Management, or a custom name the author types. A heading order is asked for only if the author wants one.
• Grouping: the portal groups every extension with the same agent under one left-nav heading, titled with the agent's name and marked with a shared agent icon. "DevOps" merges into the existing built-in DevOps group instead of creating a second one.
• Menus: every top-level frontend.menus[] node becomes a child of the agent's heading. Don't wrap menus in a node titled after the agent.
• Order: a menu node's order positions it under the heading. The agent's order suggests the heading's own position; when extensions disagree, the lowest wins. The deployment's config.json ai-menu.order overrides it, keyed by the heading id (ai-suite-agent-<slug>, e.g. ai-suite-agent-release-management).
• One agent per extension. If the author doesn't pick an agent, the field is left out. It is never written as agent: "".

Why the root, not the menu node

An earlier commit in this PR put agent on the top-level menu node. That mixed two levels in one object: the agent describes the extension, but it sat on one of its menus. It also needed a title-matching rule (a node titled like its agent became the heading), which made a node's order mean either the heading's position or the node's own. Moving agent to the root removes both.

Changes

• reference/08-parent-child-and-menus.md: the "Filing under an agent" section now covers the root field (string or { name, order }), the starter list, menus as children of the heading, menu order vs. agent order, the config.json override, the DevOps merge, and an example manifest.
• reference/02-authoring-guide.md: shows the optional root agent in the example manifest.
• duplo-extension-dev/SKILL.md: "Agent" is a Phase 1 item to settle before scaffolding, including the optional heading order.
• .claude/commands/duplo-extension.md: "agent" is in the command's clarifying-questions list.
• templates/helloworld/manifest.json: the scaffold has "agent": "DevOps" at the root, and its DevOps wrapper node is gone, so Hello World is the top-level menu.

Depends on

The platform reads the root field only with these two PRs (same ticket, DUPLOAI-3907):

• duplocloud-internal/duplo-ai-helpdesk#701: stores the root agent and returns it from the UI manifest endpoint. Until then, the backend drops unknown root fields when it saves an extension's manifest.
• duplocloud-internal/duplo-ui#5280: groups the left nav and the Activated Agents page by the root agent.

Testing

• Ten local demo extensions were converted to the root field, and each manifest validated as JSON.
• The UI and backend behaviour is covered by unit tests in the two PRs above.
• Not yet done: loading the converted extensions onto a platform running both PRs and checking the left nav.

🤖 Generated with Claude Code