agent-starter-pack 0.10.0__tar.gz → 0.11.0__tar.gz

{agent_starter_pack-0.10.0 → agent_starter_pack-0.11.0}/.claude/settings.local.json

@@ -10,8 +10,10 @@
       "Bash(set -a)",
       "Bash(. tests/cicd/.env)",
       "Bash(set +a)",
-      "Bash(bash:*)"
+      "Bash(bash:*)",
+      "Bash(ls:*)"
     ],
     "deny": []
-  }
+  },
+  "$schema": "https://json.schemastore.org/claude-code-settings.json"
 }

{agent_starter_pack-0.10.0 → agent_starter_pack-0.11.0}/.gitignore

@@ -199,4 +199,6 @@ cleanup_e2e_projects.sh
 .cloudbuild/terraform/vars/env.tfvars
 docs/.vitepress/cache
 tests/cicd/delete_gcp_resources.sh
-tests/cicd/delete_agent_engines.py
+tests/cicd/delete_agent_engines.py
+backup*
+.geminiignore

agent_starter_pack-0.11.0/CLAUDE.md

@@ -0,0 +1 @@
+GEMINI.md

agent_starter_pack-0.11.0/GEMINI.md

@@ -0,0 +1,130 @@
+# Agent Starter Pack - Coding Agent Guide
+
+This document provides essential guidance, architectural insights, and best practices for AI coding agents tasked with modifying the Google Cloud Agent Starter Pack. Adhering to these principles is critical for making safe, consistent, and effective changes.
+
+## Core Principles for AI Agents
+
+1.  **Preserve and Isolate:** Your primary objective is surgical precision. Modify *only* the code segments directly related to the user's request. Preserve all surrounding code, comments, and formatting. Do not rewrite entire files or functions to make a small change.
+2.  **Follow Conventions:** This project relies heavily on established patterns. Before writing new code, analyze the surrounding files to understand and replicate existing conventions for naming, templating logic, and directory structure.
+3.  **Search Comprehensively:** A single change often requires updates in multiple places. When modifying configuration, variables, or infrastructure, you **must** search across the entire repository, including:
+    *   `src/base_template/` (the core template)
+    *   `src/deployment_targets/` (environment-specific overrides)
+    *   `.github/` and `.cloudbuild/` (CI/CD workflows)
+    *   `docs/` (user-facing documentation)
+
+## Project Architecture Overview
+
+### Templating Engine: Cookiecutter + Jinja2
+
+The starter pack uses **Cookiecutter** to generate project scaffolding from templates that are heavily customized with the **Jinja2** templating language. Understanding the rendering process is key to avoiding errors.
+
+**Multi-Phase Template Processing:**
+
+Templates are processed in a specific order. A failure at any stage will break the project generation.
+
+1.  **Cookiecutter Variable Substitution:** Simple replacement of `{{cookiecutter.variable_name}}` placeholders with values from `cookiecutter.json`.
+2.  **Jinja2 Logic Execution:** Conditional blocks (`{% if %}`), loops (`{% for %}`), and other logic are executed. This is the most complex and error-prone stage.
+3.  **File/Directory Name Templating:** File and directory names containing Jinja2 blocks are rendered. For example, `{% if cookiecutter.cicd_runner == 'github_actions' %}.github{% else %}unused_github{% endif %}`.
+
+### Key Directory Structures
+
+-   `src/base_template/`: This is the **core template**. Most changes that should apply to all generated projects should start here.
+-   `src/deployment_targets/`: Contains files that **override or are added to** the `base_template` for a specific deployment target (e.g., `cloud_run`, `gke`, `agent_engine`). If a file exists in both `base_template` and a deployment target, the latter is typically used.
+-   `agents/`: Contains pre-packaged, self-contained agent examples. Each has its own `.template/templateconfig.yaml` to define its specific variables and dependencies.
+-   `src/cli/commands`: Contains the logic for the CLI commands, such as `create` and `setup-cicd`.
+
+### CLI Commands
+
+-   `create.py`: Handles the creation of new agent projects. It orchestrates the template processing, configuration merging, and deployment target selection.
+-   `setup_cicd.py`: Automates the setup of the CI/CD pipeline. It interacts with `gcloud` and `gh` to configure GitHub repositories, Cloud Build triggers, and Terraform backend.
+
+### Template Processing
+
+-   `template.py`: Located in `src/cli/utils`, this script contains the core logic for processing the templates. It copies the base template, overlays the deployment target files, and then applies the agent-specific files.
+
+## Critical Jinja Templating Rules
+
+Failure to follow these rules is the most common source of project generation errors.
+
+### 1. Block Balancing
+**Every opening Jinja block must have a corresponding closing block.** This is the most critical rule.
+
+-   `{% if ... %}` requires `{% endif %}`
+-   `{% for ... %}` requires `{% endfor %}`
+-   `{% raw %}` requires `{% endraw %}`
+
+**Correct:**
+```jinja
+{% if cookiecutter.deployment_target == 'cloud_run' %}
+  # Cloud Run specific content
+{% endif %}
+```
+
+### 2. Variable Usage
+Distinguish between substitution and logic:
+
+-   **Substitution (in file content):** Use double curly braces: `{{ cookiecutter.project_name }}`
+-   **Logic (in `if`/`for` blocks):** Use the variable directly: `{% if cookiecutter.use_alloydb %}`
+
+### 3. Whitespace Control
+Jinja is sensitive to whitespace. Use hyphens to control newlines and prevent unwanted blank lines in rendered files.
+
+-   `{%-` removes whitespace before the block.
+-   `-%}` removes whitespace after the block.
+
+**Example:**
+```jinja
+{%- if cookiecutter.some_option %}
+option = true
+{%- endif %}
+```
+
+## Terraform Best Practices
+
+### Unified Service Account (`app_sa`)
+The project uses a single, unified application service account (`app_sa`) across all deployment targets to simplify IAM management.
+
+-   **Do not** create target-specific service accounts (e.g., `cloud_run_sa`).
+-   Define roles for this account in `app_sa_roles`.
+-   Reference this account consistently in all Terraform and CI/CD files.
+
+### Resource Referencing
+Use consistent and clear naming for Terraform resources. When referencing resources, especially those created conditionally or with `for_each`, ensure the reference is also correctly keyed.
+
+**Example:**
+```hcl
+# Creation
+resource "google_service_account" "app_sa" {
+  for_each   = local.deploy_project_ids # e.g., {"staging" = "...", "prod" = "..."}
+  account_id = "${var.project_name}-app"
+  # ...
+}
+
+# Correct Reference
+# In a Cloud Run module for the staging environment
+service_account = google_service_account.app_sa["staging"].email
+```
+
+## CI/CD Integration (GitHub Actions & Cloud Build)
+
+The project maintains parallel CI/CD implementations. **Any change to CI/CD logic must be applied to both.**
+
+-   **GitHub Actions:** Configured in `.github/workflows/`. Uses `${{ vars.VAR_NAME }}` for repository variables.
+-   **Google Cloud Build:** Configured in `.cloudbuild/`. Uses `${_VAR_NAME}` for substitution variables.
+
+When adding a new variable or secret, ensure it is configured correctly for both systems in the Terraform scripts that manage them (e.g., `github_actions_variable` resource and Cloud Build trigger substitutions).
+
+## File Modification Checklist
+
+Before finalizing any change, verify the following:
+
+-   [ ] **Jinja Syntax:** Are all `{% if %}` and `{% for %}` blocks correctly closed with `{% endif %}` and `{% endfor %}`?
+-   [ ] **Variable Consistency:** Is the `cookiecutter.` variable name spelled correctly and used consistently across all modified files?
+-   [ ] **Cross-Target Impact:** If you changed the `base_template`, have you checked if any `deployment_targets` need corresponding updates?
+-   [ ] **CI/CD Parity:** If you modified a CI/CD workflow, did you apply the equivalent change to the other system (GitHub Actions vs. Cloud Build)?
+-   [ ] **Terraform Validation:** If you changed Terraform files, are resource references correct? Does it pass `terraform validate`?
+-   [ ] **Documentation:** Does any user-facing documentation in `docs/` need to be updated to reflect the change?
+
+### Key Tooling
+
+-   **`uv` for Python Command Execution:** `uv` is the primary tool used for managing Python dependencies and executing Python commands within the project, including CLI operations and CI/CD steps. This ensures consistent, isolated, and efficient execution environments.

{agent_starter_pack-0.10.0 → agent_starter_pack-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-starter-pack
-Version: 0.10.0
+Version: 0.11.0
 Summary: CLI to bootstrap production-ready Google Cloud GenAI agent projects from templates.
 Author-email: Google LLC <agent-starter-pack@google.com>
 License: Apache-2.0
@@ -39,7 +39,7 @@ Description-Content-Type: text/markdown
 </a> [![Launch in Cloud Shell](https://img.shields.io/badge/Launch-in_Cloud_Shell-white)](https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2Feliasecchig%2Fasp-open-in-cloud-shell&cloudshell_print=open-in-cs) ![Stars](https://img.shields.io/github/stars/GoogleCloudPlatform/agent-starter-pack?color=yellow)
 
 
-The `agent-starter-pack` is a collection of production-ready Generative AI Agent templates built for Google Cloud. <br>
+The `agent-starter-pack` is a Python package that provides a collection of production-ready Generative AI Agent templates built for Google Cloud. <br>
 It accelerates development by providing a holistic, production-ready solution, addressing common challenges (Deployment & Operations, Evaluation, Customization, Observability) in building and deploying GenAI agents.
 
 | ⚡️ Launch | 🧪 Experiment  | ✅ Deploy | 🛠️ Customize |

{agent_starter_pack-0.10.0 → agent_starter_pack-0.11.0}/README.md

@@ -16,7 +16,7 @@
 </a> [![Launch in Cloud Shell](https://img.shields.io/badge/Launch-in_Cloud_Shell-white)](https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2Feliasecchig%2Fasp-open-in-cloud-shell&cloudshell_print=open-in-cs) ![Stars](https://img.shields.io/github/stars/GoogleCloudPlatform/agent-starter-pack?color=yellow)
 
 
-The `agent-starter-pack` is a collection of production-ready Generative AI Agent templates built for Google Cloud. <br>
+The `agent-starter-pack` is a Python package that provides a collection of production-ready Generative AI Agent templates built for Google Cloud. <br>
 It accelerates development by providing a holistic, production-ready solution, addressing common challenges (Deployment & Operations, Evaluation, Customization, Observability) in building and deploying GenAI agents.
 
 | ⚡️ Launch | 🧪 Experiment  | ✅ Deploy | 🛠️ Customize |

{agent_starter_pack-0.10.0 → agent_starter_pack-0.11.0}/agents/adk_gemini_fullstack/.template/templateconfig.yaml

@@ -21,6 +21,7 @@ settings:
   extra_dependencies: ["google-adk~=1.8.0"]
   tags: ["adk"]
   frontend_type: "adk_gemini_fullstack"
+  interactive_command: "dev"
   commands:
     override:
       install: "uv sync --dev --extra jupyter && npm --prefix frontend install"

{agent_starter_pack-0.10.0 → agent_starter_pack-0.11.0}/agents/crewai_coding_crew/.template/templateconfig.yaml

@@ -21,7 +21,7 @@ settings:
     "langchain~=0.3.14",
     "langchain-community~=0.3.17", 
     "langchain-openai~=0.3.5",
-    "langgraph~=0.4.8",
-    "crewai~=0.140.0"
+    "langgraph~=0.6.2",
+    "crewai~=0.152.0"
   ]
 example_question: "How can I implement a function to sort a list in Python?"

{agent_starter_pack-0.10.0 → agent_starter_pack-0.11.0}/agents/crewai_coding_crew/tests/integration/test_agent.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# mypy: disable-error-code="union-attr"
+# mypy: ignore-errors
 from app.agent import agent
 
 

{agent_starter_pack-0.10.0 → agent_starter_pack-0.11.0}/agents/langgraph_base_react/.template/templateconfig.yaml

@@ -19,7 +19,7 @@ settings:
   extra_dependencies: [
     "langchain-google-vertexai~=2.0.7",
     "langchain~=0.3.14",
-    "langgraph~=0.4.8",
+    "langgraph~=0.6.2",
     "langchain-google-vertexai~=2.0.22",
     "langchain~=0.3.14", 
     "langchain-community~=0.3.17",

{agent_starter_pack-0.10.0 → agent_starter_pack-0.11.0}/agents/langgraph_base_react/tests/integration/test_agent.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# mypy: disable-error-code="union-attr"
+# mypy: ignore-errors
 from app.agent import agent
 
 

{agent_starter_pack-0.10.0 → agent_starter_pack-0.11.0}/agents/live_api/tests/unit/test_server.py

@@ -126,10 +126,11 @@ async def test_websocket_endpoint() -> None:
             # Verify mock interactions
             mock_genai.aio.live.connect.assert_called_once()
             assert mock_session._ws.recv.called
+            await mock_session._ws.recv.aclose()
 
 
 @pytest.mark.asyncio
-async def test_websocket_error_handling() -> None:
+def test_websocket_error_handling() -> None:
     """Test websocket error handling."""
     from app.server import app
 

{agent_starter_pack-0.10.0 → agent_starter_pack-0.11.0}/docs/.vitepress/config.js

@@ -24,6 +24,7 @@ export default defineConfig({
     nav: [
       { text: 'Home', link: '/' },
       { text: 'Guide', link: '/guide/getting-started' },
+      { text: 'Remote Templates', link: '/remote-templates/' },
       { text: 'Agents', link: '/agents/overview' },
       { text: 'CLI', link: '/cli/index.md' }
     ],
@@ -44,9 +45,11 @@ export default defineConfig({
         ]
       },
       {
-        text: 'Authoring Templates',
+        text: 'Remote Templates',
         items: [
-          { text: 'Remote Templating', link: '/guide/remote-templating' },
+          { text: 'Overview', link: '/remote-templates/' },
+          { text: 'Using Remote Templates', link: '/remote-templates/using-remote-templates' },
+          { text: 'Creating Remote Templates', link: '/remote-templates/creating-remote-templates' },
           { text: 'Template Config Reference', link: '/guide/template-config-reference' }
         ]
       },
@@ -61,6 +64,8 @@ export default defineConfig({
         text: 'CLI Reference',
         items: [
           { text: 'create', link: '/cli/create' },
+          { text: 'enhance', link: '/cli/enhance' },
+          { text: 'list', link: '/cli/list' },
           { text: 'setup-cicd', link: '/cli/setup_cicd' }
         ]
       }

{agent_starter_pack-0.10.0 → agent_starter_pack-0.11.0}/docs/agents/overview.md

@@ -8,7 +8,6 @@ The Agent Starter Pack follows a "bring your own agent" approach. It provides se
 | Agent Name | Description | Use Case |
 |------------|-------------|----------|
 | `adk_base` | A base ReAct agent implemented using Google's [Agent Development Kit](https://github.com/google/adk-python) | General purpose conversational agent |
-| `adk_gemini_fullstack` | A production-ready fullstack research agent with Gemini | Complex research and information synthesis |
 | `agentic_rag` | A RAG agent for document retrieval and Q&A | Document search and question answering |
 | `langgraph_base_react` | A base ReAct agent using LangGraph | Graph based conversational agent |
 | `crewai_coding_crew` | A multi-agent system implemented with CrewAI | Collaborative coding assistance |

agent_starter_pack-0.11.0/docs/cli/create.md

@@ -0,0 +1,176 @@
+# create
+
+Create new GCP-based AI agent projects from built-in agents or remote templates.
+
+## Usage
+
+```bash
+uvx agent-starter-pack create PROJECT_NAME [OPTIONS]
+```
+
+## Arguments
+
+- `PROJECT_NAME`: Name for your new agent project directory and base for resource naming.
+  *Note: This name will be converted to lowercase and must be 26 characters or less.*
+
+## Template Selection
+
+### `--agent`, `-a` TEMPLATE
+Specify which template to use for your agent:
+
+**Built-in agents:**
+```bash
+uvx agent-starter-pack create my-agent -a adk_base
+uvx agent-starter-pack create my-agent -a chat_agent
+```
+
+**Remote templates:**
+```bash
+# Full GitHub URL
+uvx agent-starter-pack create my-agent -a https://github.com/user/repo
+
+# Shorthand notation  
+uvx agent-starter-pack create my-agent -a github.com/user/repo@main
+
+# ADK samples shortcut
+uvx agent-starter-pack create my-agent -a adk@gemini-fullstack
+
+# Use your existing project as source
+uvx agent-starter-pack create my-agent -a local@./path/to/project
+```
+
+If omitted, you'll see an interactive list of available agents.
+
+## Deployment Options
+
+### `--deployment-target`, `-d` TARGET
+Deployment target for your agent:
+- `cloud_run` - Deploy to Google Cloud Run
+- `agent_engine` - Deploy to Google Cloud Agent Engine
+
+### `--cicd-runner` RUNNER  
+CI/CD runner to use:
+- `google_cloud_build` - Use Google Cloud Build
+- `github_actions` - Use GitHub Actions
+
+### `--region` REGION
+GCP region for deployment (default: `us-central1`)
+
+## Data & Storage Options
+
+### `--include-data-ingestion`, `-i`
+Include data ingestion pipeline components in the project.
+
+### `--datastore`, `-ds` DATASTORE
+Type of datastore for data ingestion (requires `--include-data-ingestion`):
+- `vertex_ai_search`
+- `vertex_ai_vector_search` 
+- `alloydb`
+
+### `--session-type` TYPE
+Session storage type (for Cloud Run deployment):
+- `in_memory` - Store sessions in memory
+- `alloydb` - Store sessions in AlloyDB
+- `agent_engine` - Use Agent Engine session management
+
+## Project Creation Options
+
+### `--output-dir`, `-o` DIRECTORY
+Output directory for the project (default: current directory)
+
+### `--in-folder`
+Create agent files directly in the current directory instead of creating a new project subdirectory.
+
+**Standard behavior:**
+```bash
+uvx agent-starter-pack create my-agent -a template
+# Creates: ./my-agent/[project files]
+```
+
+**In-folder behavior:**
+```bash  
+uvx agent-starter-pack create my-agent -a template --in-folder
+# Creates: ./[project files] (in current directory)
+```
+
+**Use cases:**
+- Adding agent capabilities to existing projects
+- Working within established repository structures
+- Containerized development environments
+
+**Automatic Backup:** When using `--in-folder`, a complete backup of your directory is automatically created as `.backup_[dirname]_[timestamp]` before any changes are made.
+
+## Automation Options
+
+### `--auto-approve`
+Skip interactive confirmation prompts for GCP credentials and region.
+
+### `--skip-checks`
+Skip verification checks for GCP authentication and Vertex AI connection.
+
+### `--debug`
+Enable debug logging for troubleshooting.
+
+## Examples
+
+### Basic Usage
+
+```bash
+# Create a new project interactively
+uvx agent-starter-pack create my-agent-project
+
+# Create with specific built-in agent
+uvx agent-starter-pack create my-agent -a adk_base -d cloud_run
+```
+
+### Remote Templates
+
+```bash
+# Use ADK samples
+uvx agent-starter-pack create my-agent -a adk@gemini-fullstack
+
+# Use GitHub repository
+uvx agent-starter-pack create my-agent -a https://github.com/user/my-template
+
+# Use shorthand notation with branch
+uvx agent-starter-pack create my-agent -a github.com/user/template@develop
+
+# Use your existing project  
+uvx agent-starter-pack create my-agent -a local@./my-project
+```
+
+### Advanced Configuration
+
+```bash
+# Include data ingestion with specific datastore
+uvx agent-starter-pack create my-rag-agent -a adk_base -i -ds alloydb -d cloud_run
+
+# Create with custom region and CI/CD
+uvx agent-starter-pack create my-agent -a template-url --region europe-west1 --cicd-runner github_actions
+
+# In-folder creation (add to existing project)
+uvx agent-starter-pack create my-agent -a adk@data-science --in-folder
+
+# Skip all prompts for automation
+uvx agent-starter-pack create my-agent -a template-url --auto-approve --skip-checks
+```
+
+### Output Directory
+
+```bash
+# Create in specific directory
+uvx agent-starter-pack create my-agent -o ./projects/
+
+# Create in current directory with in-folder
+uvx agent-starter-pack create existing-project -a template-url --in-folder
+```
+
+## Related Commands
+
+- [`enhance`](./enhance.md) - Add agent capabilities to existing projects (automatically uses `--in-folder`)
+- [`list`](./list.md) - List available templates and agents
+
+## See Also
+
+- [Using Remote Templates](../remote-templates/using-remote-templates.md) - Complete guide for using remote templates
+- [Creating Remote Templates](../remote-templates/creating-remote-templates.md) - Guide for creating your own templates

agent_starter_pack-0.11.0/docs/cli/enhance.md

@@ -0,0 +1,180 @@
+# enhance
+
+The `enhance` command adds agent-starter-pack capabilities to existing projects without creating a new directory. It's designed for upgrading prototypes to production-ready agents in-place.
+
+## Usage
+
+```bash
+uvx agent-starter-pack enhance [TEMPLATE_PATH] [OPTIONS]
+```
+
+## Arguments
+
+- `TEMPLATE_PATH` (optional): Can be:
+  - `.` (default) - Use current directory as template
+  - Local directory path - Use another local directory as template  
+  - Agent name - Use a built-in agent (e.g., `adk_base`)
+  - Remote template - Use a remote template (e.g., `adk@gemini-fullstack`)
+
+## Options
+
+The `enhance` command supports all the same options as [`create`](./create.md), plus:
+
+### `--base-template` TEMPLATE
+Override the base template for inheritance when enhancing your existing project. Available base templates include:
+- `adk_base` - Basic agent template (default)
+- `langgraph_base_react` - LangGraph-based ReAct agent
+- `agentic_rag` - RAG-enabled agent template
+
+### Other Options
+- `--name, -n` - Project name (defaults to current directory name)
+- `--deployment-target, -d` - Deployment target (`agent_engine`, `cloud_run`)
+- `--include-data-ingestion, -i` - Include data ingestion pipeline
+- `--session-type` - Session storage type
+- `--auto-approve` - Skip confirmation prompts
+- And all other `create` command options
+
+## Examples
+
+### Basic Enhancement
+
+```bash
+# Enhance current project with default template
+uvx agent-starter-pack enhance
+
+# Enhance with a specific agent template
+uvx agent-starter-pack enhance adk@gemini-fullstack
+
+# Enhance with custom project name
+uvx agent-starter-pack enhance --name my-enhanced-agent
+```
+
+### Advanced Options
+
+```bash
+# Enhance with specific deployment target
+uvx agent-starter-pack enhance adk@data-science --deployment-target cloud_run
+
+# Enhance with data ingestion capabilities
+uvx agent-starter-pack enhance --include-data-ingestion --datastore alloydb
+
+# Enhance with custom session storage
+uvx agent-starter-pack enhance --session-type alloydb
+```
+
+### Base Template Inheritance
+
+```bash
+# Enhance current project with LangGraph capabilities
+uvx agent-starter-pack enhance . --base-template langgraph_base_react
+
+# Enhance with RAG-enabled base template
+uvx agent-starter-pack enhance . --base-template agentic_rag
+```
+
+## Project Structure Validation
+
+The enhance command validates your project structure and provides guidance:
+
+**✅ Ideal Structure:**
+```
+your-project/
+├── app/
+│   └── agent.py    # Your agent code
+├── tests/
+└── README.md
+```
+
+**⚠️ Missing /app Folder:**
+If your project doesn't have an `/app` folder, the command will:
+1. Display a warning about project structure
+2. Explain the expected structure
+3. Ask for confirmation to proceed (unless `--auto-approve` is used)
+
+## How It Works
+
+The `enhance` command is essentially an alias for:
+```bash
+uvx agent-starter-pack create PROJECT_NAME --agent TEMPLATE --in-folder
+```
+
+It automatically:
+- Uses the current directory name as the project name (unless `--name` is specified)
+- Enables `--in-folder` mode to template directly into the current directory
+- Validates the project structure for compatibility
+- Applies the same file merging logic as the `create` command
+
+### Base Template Inheritance
+
+When enhancing your existing project (using `local@.` or `local@/path/to/project`), the enhance command will:
+
+1. **Show current inheritance**: Display which base template your project inherits from
+2. **Provide guidance**: Show available alternative base templates and how to use them
+3. **Support CLI override**: Use `--base-template` to override the base template specified in `pyproject.toml`
+
+The inheritance hierarchy works as follows:
+```
+Your Existing Project
+    ↓ (inherits from)
+Base Template (adk_base, langgraph_base_react, etc.)
+    ↓ (provides)
+Core Infrastructure & Capabilities
+```
+
+## Use Cases
+
+**Prototype to Production:**
+```bash
+# You have a prototype agent in /app/agent.py
+uvx agent-starter-pack enhance adk@production-ready
+```
+
+**Add Infrastructure:**
+```bash
+# Add Terraform and deployment capabilities
+uvx agent-starter-pack enhance --deployment-target cloud_run
+```
+
+**Add Data Pipeline:**
+```bash
+# Add data ingestion to existing agent
+uvx agent-starter-pack enhance --include-data-ingestion --datastore alloydb
+```
+
+**Upgrade Agent Base:**
+```bash
+# Upgrade from basic to advanced agent template
+uvx agent-starter-pack enhance adk@gemini-fullstack
+
+# Or change base template inheritance
+uvx agent-starter-pack enhance . --base-template langgraph_base_react
+```
+
+## Automatic Backup
+
+The `enhance` command automatically creates a complete backup of your project before making any changes:
+
+- **Location:** `.backup_[dirname]_[timestamp]` in the parent directory
+- **Contents:** Complete copy of your entire project directory
+- **Timing:** Created before any template files are applied
+
+## Best Practices
+
+1. **Review Backup:** Check that the backup was created successfully
+2. **Follow Structure:** Organize your agent code in `/app/agent.py` for best compatibility  
+3. **Test Locally:** Use `--auto-approve` in CI/CD but test interactively first
+4. **Review Changes:** After enhancement, review the generated files and configuration
+
+## Troubleshooting
+
+**"Project structure warning"**
+- Organize your agent code in an `/app` folder
+- Use `--auto-approve` to skip the confirmation prompt
+
+**"Enhancement cancelled"**
+- Create an `/app` folder with your `agent.py` file
+- Re-run the command
+
+**"Dependency conflicts"**
+- Review and resolve conflicts in your `pyproject.toml`
+- Consider using a virtual environment