feat: add adk-py@ shortcut for google/adk-python contributing samples (#918)

Add a new shortcut pattern `adk-py@<sample-name>` that maps to
`https://github.com/google/adk-python/tree/main/contributing/samples/<sample-name>`.

This allows users to create projects from ADK Python contributing
samples using a concise syntax, e.g.:
  uvx agent-starter-pack create -a adk-py@code-execution

instead of the full URL:
  uvx agent-starter-pack create -a https://github.com/google/adk-python/tree/main/contributing/samples/code-execution

Author: eliasecchig

agent_starter_pack/cli/commands/create.py

@@ -265,7 +265,7 @@ def normalize_project_name(project_name: str) -> str:
 @click.option(
     "--agent",
     "-a",
-    help="Template identifier to use. Can be a local agent name (e.g., `chat_agent`), a local path (`local@/path/to/template`), an `adk-samples` shortcut (e.g., `adk@data-science`), or a remote Git URL. Both shorthand (e.g., `github.com/org/repo/path@main`) and full URLs from your browser (e.g., `https://github.com/org/repo/tree/main/path`) are supported. Lists available local templates if omitted.",
+    help="Template identifier to use. Can be a local agent name (e.g., `chat_agent`), a local path (`local@/path/to/template`), an `adk-samples` shortcut (e.g., `adk@data-science`), an `adk-python` shortcut (e.g., `adk-py@code-execution`), or a remote Git URL. Both shorthand (e.g., `github.com/org/repo/path@main`) and full URLs from your browser (e.g., `https://github.com/org/repo/tree/main/path`) are supported. Lists available local templates if omitted.",
 )
 @click.option(
     "--output-dir",

agent_starter_pack/cli/commands/enhance.py

@@ -1044,7 +1044,7 @@ def enhance(
     TEMPLATE_PATH can be:
     - A local directory path (e.g., . for current directory)
     - An agent name (e.g., adk)
-    - A remote template (e.g., adk@data-science)
+    - A remote template (e.g., adk@data-science, adk-py@code-execution)
 
     The command will validate your project structure and provide guidance if needed.
     """

agent_starter_pack/cli/utils/logging.py

@@ -128,7 +128,7 @@ def display_welcome_banner(
             version=version,
             motto=motto,
         )
-    elif agent and agent.startswith("adk@"):
+    elif agent and (agent.startswith("adk@") or agent.startswith("adk-py@")):
         panel = _build_banner(
             line1=(
                 "Powered by [link=https://goo.gle/agent-starter-pack]"

agent_starter_pack/cli/utils/remote_template.py

@@ -65,6 +65,16 @@ def parse_agent_spec(agent_spec: str) -> RemoteTemplateSpec | None:
             is_adk_samples=True,
         )
 
+    # Check for adk-py@ shortcut (maps to google/adk-python contributing samples)
+    if agent_spec.startswith("adk-py@"):
+        sample_name = agent_spec[7:]  # Remove "adk-py@" prefix
+        return RemoteTemplateSpec(
+            repo_url="https://github.com/google/adk-python",
+            template_path=f"contributing/samples/{sample_name}",
+            git_ref="main",
+            is_adk_samples=True,
+        )
+
     # GitHub /tree/ URL pattern
     tree_pattern = r"^(https?://[^/]+/[^/]+/[^/]+)/tree/([^/]+)/(.*)$"
     match = re.match(tree_pattern, agent_spec)

tests/cli/utils/test_remote_template.py

@@ -69,6 +69,24 @@ def test_parse_adk_shortcut(self) -> None:
         assert spec.git_ref == "main"
         assert spec.is_adk_samples is True
 
+    def test_parse_adk_py_shortcut(self) -> None:
+        """Test parsing ADK Python shortcut format"""
+        spec = parse_agent_spec("adk-py@code-execution")
+        assert spec is not None
+        assert spec.repo_url == "https://github.com/google/adk-python"
+        assert spec.template_path == "contributing/samples/code-execution"
+        assert spec.git_ref == "main"
+        assert spec.is_adk_samples is True
+
+    def test_parse_adk_py_shortcut_underscore_name(self) -> None:
+        """Test parsing ADK Python shortcut with underscore name"""
+        spec = parse_agent_spec("adk-py@agent_engine_code_execution")
+        assert spec is not None
+        assert spec.repo_url == "https://github.com/google/adk-python"
+        assert spec.template_path == "contributing/samples/agent_engine_code_execution"
+        assert spec.git_ref == "main"
+        assert spec.is_adk_samples is True
+
     def test_parse_full_url_with_path_and_ref(self) -> None:
         """Test parsing full URL with path and ref"""
         spec = parse_agent_spec("https://github.com/org/repo/path/to/template@develop")
@@ -504,6 +522,9 @@ def test_template_validation_scenarios(self) -> None:
             # ADK samples
             ("adk@academic-research", True),
             ("adk@custom-agent", True),
+            # ADK Python samples
+            ("adk-py@code-execution", True),
+            ("adk-py@agent_engine_code_execution", True),
             # GitHub URLs
             ("https://github.com/org/repo", True),
             ("https://github.com/org/repo/path@branch", True),
@@ -585,6 +606,15 @@ def test_parse_adk_shortcut_not_affected(self) -> None:
         assert spec.git_ref == "main"
         assert spec.is_adk_samples is True
 
+    def test_parse_adk_py_shortcut_not_affected(self) -> None:
+        """Ensure the adk-py@ shortcut remains unaffected."""
+        spec = parse_agent_spec("adk-py@code-execution")
+        assert spec is not None
+        assert spec.repo_url == "https://github.com/google/adk-python"
+        assert spec.template_path == "contributing/samples/code-execution"
+        assert spec.git_ref == "main"
+        assert spec.is_adk_samples is True
+
     def test_parse_github_shorthand_not_affected(self) -> None:
         """Ensure GitHub shorthand parsing remains unaffected."""
         spec = parse_agent_spec("org/repo")