docs: Add 'check before building' triggers to amplifier-expert

[colombod]

Summary

Add "check before building" guidance to prevent module duplication in the Amplifier ecosystem.

Tracking issue: https://github.com/microsoft-amplifier/amplifier-support/issues/43

Changes

File	Change
agents/module-catalog-expert.md	NEW - Focused catalog expert for module discovery
behaviors/module-catalog-expert.yaml	NEW - Thin behavior (uses @mention, not context.include)
bundle.md	UPDATED - Includes amplifier:behaviors/module-catalog-expert

Architecture

amplifier:module-catalog-expert (spawned on demand)
    │
    └─► @amplifier:docs/MODULES.md (~4,600 tokens)
        Only loads when agent runs, not during bundle composition

Why a Separate Agent?

Approach	Problem
Add to amplifier-expert	Bloats general expert with catalog data
Use context.include	Propagates during composition
Focused agent with @mention	Loads only when specifically querying catalog ✓

Related

• Companion PR: docs: Add 'Before Building New Functionality' guidance to AWARENESS_INDEX amplifier-foundation#55
• Issue: https://github.com/microsoft-amplifier/amplifier-support/issues/43

[bkrabach]

Review: PR #211 - "Check before building" triggers

Thanks for this PR! The intent is valuable - preventing duplicate work by checking existing modules before building new ones. However, I have some concerns about the implementation approach.

Issue 1: Formatting Bug - Duplicate "Examples:" Header

The diff shows two Examples:\n\n strings in the description - one before the new example and one before the existing examples. This should be a single header with all examples underneath.

Issue 2: Architectural Concern - context.include Propagates

Adding amplifier:docs/MODULES.md to the behavior's context.include will cause it to propagate to all parent bundles that include the amplifier-expert behavior.

This defeats the context sink pattern that amplifier-expert is designed for:

• Root sessions should stay lightweight (~500 tokens for delegation awareness)
• Heavy docs (~20KB for MODULES.md) should load only when amplifier-expert actually runs
• context.include propagates during composition, meaning ANY bundle that includes amplifier-expert behavior would get MODULES.md in their context

Issue 3: MODULES.md is Already @mentioned

Line 88 of amplifier-expert.md already has:

- @amplifier:docs/MODULES.md - Module ecosystem

This @mention in the agent's markdown body is the correct approach - it loads only when the agent's instruction is used, not when other sessions merely have access to delegate to it.

If this @mention isn't currently loading (being treated as a "soft reference"), the fix should ensure the @mention works, not add a second loading mechanism via context.include.

Suggested Alternative

If the goal is to add "check before building" guidance:

1. Fix the duplicate Examples header - merge under single header
2. Don't add MODULES.md to context.include - it's already @mentioned in the body
3. Consider lighter description text - keep trigger in description, move procedural detail to body:

   # Instead of:
   "**REQUIRED: Before building new modules/tools/capabilities**, consult this agent to check MODULES.md for existing solutions. Do not reinvent—reuse or extend."
   
   # Consider:
   "**REQUIRED: Before building new capabilities**, check for existing modules first."
   

The foundation PR #55 adding the directive to AWARENESS_INDEX.md is fine - that's a lightweight pointer. But this PR's context.include change would have unintended token cost consequences.

Happy to discuss further!

[colombod]

Addressing Feedback

Thanks for the detailed review, Brian! You caught two important issues.

Fixed: Duplicate "Examples:" Header ✓

Removed the duplicate.

Fixed: context.include Propagation ✓

You're absolutely right - context.include propagates during composition, which would defeat the context sink pattern.

The fix: Removed context.include from behaviors/module-catalog.yaml. MODULES.md is now loaded only via the @amplifier:docs/MODULES.md mention in the agent body (agents/module-catalog.md line 18), which loads only when the agent actually runs.

Note: module-catalog is Intentional

This PR introduces a new focused agent called module-catalog - it's not a typo for amplifier-expert. The rationale:

Agent	Purpose	Loads
amplifier-expert	General ecosystem guidance	ecosystem-overview.md
module-catalog	Focused catalog queries	MODULES.md (only when spawned)

This follows the context sink pattern more precisely - a lightweight, focused agent for "what modules exist?" queries, rather than adding more weight to the general-purpose expert.

Happy to discuss if you'd prefer keeping it all in amplifier-expert!

[colombod]

Correction: You Were Right

Brian, apologies for the confusion in my previous comment. You were correct - the module-catalog agent did not exist in the PR when you reviewed it.

What happened: My local commit had the new files, but the push to GitHub failed silently. When you reviewed, the PR only contained changes to amplifier-expert.md and amplifier-expert.yaml - no module-catalog files at all.

Now fixed: I've force-pushed the complete commit. The PR now includes:

File	Status
agents/module-catalog.md	NEW - the focused catalog agent
behaviors/module-catalog.yaml	NEW - thin behavior (no context.include, uses @mention)
bundle.md	UPDATED - includes amplifier:behaviors/module-catalog

Also fixed:

• Removed context.include from the behavior (per your feedback about propagation)
• Fixed the duplicate "Examples:" header

Please re-review when you have a chance. The module-catalog agent now actually exists in the PR.