docs: clarify behavior bundle guidance

AGENTS.md

@@ -62,6 +62,14 @@ root instruction truthy and changes its existing behavior-body inheritance.
 Keep the injection non-mutating because the foundation registry caches bundles;
 foundation's prompt factory resolves these optional files freshly per request.
 
+## Bundle guidance ownership
+
+Document reusable capabilities as behavior bundles added with `--app` to the
+existing host. Document selectable roots separately; new-host examples use
+Anchors and preserve `@anchors:context/system.md` when their root has a body.
+This is documentation/help guidance only: do not change composition defaults or
+existing root selections to enforce it.
+
 ## Update reporting
 
 Keep report labels separate from update eligibility: a missing mutable cache is

README.md

@@ -45,6 +45,27 @@ amplifier run --bundle my-bundle "Your prompt"
 
 **Environment variables**: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `AZURE_OPENAI_API_KEY`, `GOOGLE_API_KEY` detected automatically during `amplifier init`.
 
+## Add a Capability Behavior
+
+Add a reusable capability to the CLI's existing host with `--app`. The behavior
+is composed into every session without replacing the selected root bundle:
+
+```bash
+amplifier bundle add 'git+https://github.com/microsoft/amplifier-bundle-recipes@main#subdirectory=behaviors/recipes.yaml' --app
+```
+
+Register and select a user-owned complete root separately. The name is read
+from bundle metadata unless you supply an optional `--name` alias:
+
+```bash
+amplifier bundle add 'git+https://github.com/org/my-host@main#subdirectory=bundle.md' --name my-host
+amplifier bundle use my-host
+```
+
+Anchors is built in and the default root, so it does not need to be added.
+`amplifier bundle use anchors` is sufficient when you want to select it
+explicitly. When authoring a new root, use Anchors as its canonical base.
+
 ## Commands
 
 ### Configuration Commands
@@ -55,7 +76,8 @@ amplifier bundle current                              # Show active bundle
 amplifier bundle use <name> [--local|--project|--global]  # Set active bundle
 amplifier bundle list                                 # List available bundles
 amplifier bundle show <name>                          # Show bundle details
-amplifier bundle add <git-url> [--name alias]         # Register a bundle (name auto-derived)
+amplifier bundle add <behavior-url> --app             # Add behavior to every session
+amplifier bundle add <root-url> [--name alias]        # Register selectable root (name auto-derived)
 amplifier bundle remove <name>                        # Unregister a bundle
 amplifier bundle clear                                # Reset to default (anchors)
 

amplifier_app_cli/commands/bundle.py

@@ -892,33 +892,30 @@ def _get_bundle_source_scope(app_settings: AppSettings) -> str:
     help="Add as app bundle (automatically composed with all sessions)",
 )
 def bundle_add(uri: str, name_override: str | None, app: bool):
-    """Add a bundle to the registry for discovery.
+    """Add a behavior or root bundle.
 
     URI is the location of the bundle (git+https://, file://, etc.).
     The bundle name is automatically extracted from the bundle's metadata.
     Use --name to specify a custom alias instead.
 
-    Use --app to add as an "app bundle" that is automatically composed onto
-    every session, regardless of which primary bundle is used. This is useful
-    for team-wide behaviors, support bundles, or personal preferences.
+    Use --app for a behavior that is automatically composed onto every session,
+    regardless of the selected root bundle. Omit --app to register a selectable
+    root, then activate it with `amplifier bundle use <name>`.
 
     Examples:
 
         \b
-        # Auto-derives name from bundle metadata
-        amplifier bundle add git+https://github.com/microsoft/amplifier-bundle-recipes@main
+        # Add a behavior to the existing host
+        amplifier bundle add git+https://github.com/org/my-bundle@main#subdirectory=behaviors/my-capability.yaml --app
 
         \b
-        # Use custom alias
-        amplifier bundle add git+https://github.com/microsoft/amplifier-bundle-recipes@main --name my-recipes
+        # Register a user-owned complete root under an alias
+        amplifier bundle add git+https://github.com/org/my-host@main#subdirectory=bundle.md --name my-host
+        amplifier bundle use my-host
 
-        \b
-        # Local bundle
-        amplifier bundle add file:///path/to/bundle
-
-        \b
-        # Add as app bundle (always active)
-        amplifier bundle add git+https://github.com/org/team-bundle@main --app
+    Anchors is built in and the default root, so it does not need to be added.
+    Run `amplifier bundle use anchors` only to select it explicitly. When
+    authoring a new root, use Anchors as its canonical base.
     """
     from amplifier_foundation import load_bundle
 

amplifier_app_cli/data/skills/goal-batch/SKILL.md

@@ -1,18 +1,11 @@
 ---
 name: goal-batch
 description: >
-  Batch independent work into isolated /goal lanes — one worktree, branch, and
-  tmux session each — get your approval, then verify and merge every lane
-  yourself. Use when work decomposes into pieces that can run at the same
-  time: "run these in parallel", "goal-batch", "launch lanes for these",
-  "work these N tasks simultaneously", "batch these as goals". Nothing
-  launches until you've seen the lane split and said go, and this is NOT
-  fire-and-forget: the orchestrating session re-runs the full suite after
-  every merge and never accepts a lane's own claim that it finished. NOT for
-  bounded edits that each end in their own PR — use mass-change for that. For
-  continuous refill-on-drain parallel work toward an outcome, use
-  ten-lane-highway instead. Requires git, tmux, the amplifier CLI on PATH,
-  and the goalify and monitor skills.
+  Batch independent work into isolated /goal lanes. Triggers: "run these in
+  parallel", "goal-batch", "launch lanes for these", "work these N tasks
+  simultaneously", "batch these as goals". Show the plan; require explicit
+  user approval before launch; verify results before landing. Not for bounded
+  per-PR edits (mass-change) or continuous refill-on-drain work (ten-lane-highway).
 version: 2.0.0
 user-invocable: true
 argument-hint: "<the work to batch, or where it is enumerated>"

docs/CONTEXT_LOADING.md

@@ -11,8 +11,13 @@
 ---
 bundle:
   name: my-bundle
+
+includes:
+  - bundle: git+https://github.com/microsoft/amplifier-foundation@main#subdirectory=bundles/anchors/bundle.md
 ---
 
+@anchors:context/system.md
+
 You are a helpful Python development assistant.
 
 Follow PEP 8 style guidelines and use type hints.
@@ -27,8 +32,13 @@ The markdown body becomes the system instruction.
 ---
 bundle:
   name: dev-bundle
+
+includes:
+  - bundle: git+https://github.com/microsoft/amplifier-foundation@main#subdirectory=bundles/anchors/bundle.md
 ---
 
+@anchors:context/system.md
+
 You are an Amplifier development assistant.
 
 Project context:
@@ -45,15 +55,29 @@ The @mentioned files load automatically and are added as context.
 
 **Bundles** provide organized, shareable packages of context files. Most shared context is now organized in bundles rather than standalone files.
 
-**Foundation bundle** provides:
+The Foundation library also publishes namespace resources such as:
 - `@foundation:context/IMPLEMENTATION_PHILOSOPHY.md`
 - `@foundation:context/MODULAR_DESIGN_PHILOSOPHY.md`
 - `@foundation:context/shared/common-agent-base.md`
 
-**Usage in bundles**:
+For a new complete host, include Anchors and preserve its system instruction
+before adding your own body:
 ```markdown
+# my-host/bundle.md
+---
+bundle:
+  name: my-host
+
+includes:
+  - bundle: git+https://github.com/microsoft/amplifier-foundation@main#subdirectory=bundles/anchors/bundle.md
+
+---
+
+@anchors:context/system.md
 @foundation:context/shared/common-agent-base.md
 @foundation:context/IMPLEMENTATION_PHILOSOPHY.md
+
+You are a helpful domain-specific development assistant.
 ```
 
 **→ [Bundle Guide](https://github.com/microsoft/amplifier-foundation/blob/main/docs/BUNDLE_GUIDE.md)** for complete bundle documentation.
@@ -207,10 +231,12 @@ Quality guidelines...
 ---
 bundle:
   name: specialized
-  extends: foundation  # YAML config inheritance
+
+includes:
+  - bundle: git+https://github.com/microsoft/amplifier-foundation@main#subdirectory=bundles/anchors/bundle.md
 ---
 
-@foundation:context/shared/common-base.md
+@anchors:context/system.md
 
 Additionally, you specialize in database architecture.
 
@@ -225,9 +251,11 @@ Context:
 - **Explicit** - Clear what's being included
 - **Flexible** - Can compose multiple shared files
 
-### Note on Bundle Inheritance
+### Note on Bundle Composition
 
-The `extends:` field in YAML frontmatter inherits configuration (modules, settings) but NOT markdown body. Use @mentions to share markdown content across bundles.
+The `includes:` list composes bundle configuration. A root bundle that supplies
+its own markdown body should explicitly include `@anchors:context/system.md`;
+use @mentions to share additional instruction files across bundles.
 
 ## Provider-Specific Handling
 
@@ -359,8 +387,13 @@ All context inline in bundle markdown:
 ---
 bundle:
   name: simple
+
+includes:
+  - bundle: git+https://github.com/microsoft/amplifier-foundation@main#subdirectory=bundles/anchors/bundle.md
 ---
 
+@anchors:context/system.md
+
 You are a helpful assistant.
 
 Be concise and clear.
@@ -377,10 +410,12 @@ References shared context:
 ---
 bundle:
   name: dev
-  extends: foundation  # YAML config inheritance
+
+includes:
+  - bundle: git+https://github.com/microsoft/amplifier-foundation@main#subdirectory=bundles/anchors/bundle.md
 ---
 
-@foundation:context/shared/common-base.md
+@anchors:context/system.md
 
 Development-specific context:
 - @AGENTS.md
@@ -462,8 +497,13 @@ If files reference each other in a loop, cycle detection prevents infinite recur
 ---
 bundle:
   name: researcher
+
+includes:
+  - bundle: git+https://github.com/microsoft/amplifier-foundation@main#subdirectory=bundles/anchors/bundle.md
 ---
 
+@anchors:context/system.md
+
 You are a research specialist.
 
 Context:
@@ -479,10 +519,12 @@ Gather information systematically and cite sources.
 ---
 bundle:
   name: team-standard
-  extends: foundation  # YAML config inheritance
+
+includes:
+  - bundle: git+https://github.com/microsoft/amplifier-foundation@main#subdirectory=bundles/anchors/bundle.md
 ---
 
-@foundation:context/shared/common-base.md
+@anchors:context/system.md
 
 Team-specific context:
 - @project:context/team-conventions.md