From 0edb8e98654fe984dbaec6a6786c438f721d75f6 Mon Sep 17 00:00:00 2001 From: Brian Krabach Date: Tue, 13 Jan 2026 08:54:41 -0800 Subject: [PATCH] docs: Add development hygiene context and behavior bundle MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add comprehensive documentation explaining Amplifier CLI installation architecture and development best practices: - context/development-hygiene.md: Explains why ~/.amplifier/cache cannot be deleted directly, the 'amplifier reset' command, local source overrides, shadow environments, and project-local venvs - behaviors/amplifier-dev.yaml: Behavior bundle that includes the development hygiene context for AI assistants working on Amplifier This helps prevent anti-patterns like directly manipulating the global install or cache directories. 🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier) Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com> --- behaviors/amplifier-dev.yaml | 8 ++ context/development-hygiene.md | 186 +++++++++++++++++++++++++++++++++ 2 files changed, 194 insertions(+) create mode 100644 behaviors/amplifier-dev.yaml create mode 100644 context/development-hygiene.md diff --git a/behaviors/amplifier-dev.yaml b/behaviors/amplifier-dev.yaml new file mode 100644 index 00000000..db834db3 --- /dev/null +++ b/behaviors/amplifier-dev.yaml @@ -0,0 +1,8 @@ +bundle: + name: amplifier-dev-behavior + version: 1.0.0 + description: Development hygiene and best practices for Amplifier CLI users + +context: + include: + - amplifier:context/development-hygiene.md diff --git a/context/development-hygiene.md b/context/development-hygiene.md new file mode 100644 index 00000000..bdc8a68d --- /dev/null +++ b/context/development-hygiene.md @@ -0,0 +1,186 @@ +# Amplifier CLI Installation Architecture & Development Hygiene + +This guide explains how the Amplifier CLI installation works and the correct patterns for development work. + +## How Amplifier is Installed + +### Installation Flow + +1. **Entry point**: `uv tool install git+https://github.com/microsoft/amplifier` +2. **Tool directory**: Creates `~/.local/share/uv/tools/amplifier/` (bin, lib, site-packages) +3. **Cache directory**: Clones `amplifier-core`, `amplifier-app-cli`, and other packages to `~/.amplifier/cache/` +4. **Editable installs**: The site-packages contain **links** pointing to the cache versions + +### Runtime Behavior + +When Amplifier launches: +1. Installs "well-known" providers (clone to cache → editable install) +2. Downloads bundles and modules on demand (same pattern) +3. **The actual running code is the code in `~/.amplifier/cache/`** + +### Directory Structure + +``` +~/.local/share/uv/tools/amplifier/ +├── bin/amplifier # Entry point script +└── lib/python3.x/site-packages/ + └── amplifier_*.egg-link # LINKS to ~/.amplifier/cache/ + +~/.amplifier/ +├── cache/ # Downloaded packages - THE RUNNING CODE +│ ├── amplifier-core-{hash}/ +│ ├── amplifier-foundation-{hash}/ +│ ├── amplifier-module-provider-anthropic-{hash}/ +│ └── ... +├── registry.json # Bundle name → source mappings +├── settings.yaml # Global user settings +├── keys.env # API keys +└── projects/ # Session transcripts +``` + +## CRITICAL: Never Delete the Cache Directly + +**NEVER run:** +```bash +rm -rf ~/.amplifier/cache/ # DANGEROUS - breaks Amplifier +rm -rf ~/.amplifier/ # DANGEROUS - breaks Amplifier +``` + +**Why this breaks things:** +1. The CLI's site-packages contain **links** to cache files +2. Without the cache, the CLI cannot run ANY commands +3. It can't even download modules to repopulate because it needs modules to do that +4. You end up in a broken state requiring manual `uv tool install` to recover + +### The Right Way: `amplifier reset` + +Use the reset command to safely clear and reinstall: + +```bash +# Interactive mode - choose what to preserve +amplifier reset + +# Clear only cache and registry (preserves settings, keys, projects) +amplifier reset --remove cache,registry -y + +# Preview what would be removed without changes +amplifier reset --dry-run + +# Nuclear option - remove everything +amplifier reset --full -y +``` + +**How reset works safely:** +1. Cleans UV cache +2. Uninstalls amplifier via `uv tool uninstall` +3. Removes specified ~/.amplifier contents +4. **Reinstalls** from `git+https://github.com/microsoft/amplifier` +5. Launches fresh amplifier + +The reinstall step is what makes this safe - it repopulates everything from scratch. + +## Development Patterns + +### Don't Modify ~/.amplifier/cache/ for Development + +The cache is for RUNNING the installed CLI, not for development work. + +**Anti-patterns:** +- Reading cache code to understand how something works (use cloned repos) +- Editing cache files to test changes (changes are invisible to git) +- Using cache paths in your work (they're ephemeral) + +**Instead:** +- Clone the repo you need: `git clone https://github.com/microsoft/amplifier-module-xyz.git` +- Or add as submodule in a workspace: `git submodule add https://github.com/...` + +### Project-Local Source Overrides + +To test local changes without modifying the global installation: + +**Create `.amplifier/settings.yaml` in your project:** + +```yaml +sources: + # Override a module to use local checkout + amplifier-module-xyz: + type: local + path: ./amplifier-module-xyz + + # Override core for kernel development + amplifier-core: + type: local + path: ./amplifier-core +``` + +### Settings Scope Hierarchy + +| Scope | File | Precedence | Use Case | +|-------|------|------------|----------| +| Local | `.amplifier/settings.local.yaml` | Highest | Personal (gitignored) | +| Project | `.amplifier/settings.yaml` | Medium | Team-shared | +| Global | `~/.amplifier/settings.yaml` | Lowest | User defaults | + +**Module Resolution Order:** +1. Environment variable: `AMPLIFIER_MODULE_=` +2. Workspace convention: `.amplifier/modules//` +3. Project config: `.amplifier/settings.yaml` sources +4. User config: `~/.amplifier/settings.yaml` sources +5. Bundle/profile source field +6. Installed package (cache) + +### Shadow Environments (Recommended for Testing) + +For testing local changes in complete isolation, use **shadow environments** (available via the foundation bundle): + +```python +# Create isolated environment with your local changes +shadow.create(local_sources=[ + "~/repos/amplifier-core:microsoft/amplifier-core", + "~/repos/amplifier-module-xyz:microsoft/amplifier-module-xyz" +]) + +# Install and test in the shadow - uses YOUR local code +shadow.exec(shadow_id, "uv tool install git+https://github.com/microsoft/amplifier") +shadow.exec(shadow_id, "amplifier run 'test my changes'") + +# Clean up +shadow.destroy(shadow_id) +``` + +**Why shadow environments:** +- Complete OS-level isolation (containerized) +- Your local changes are snapshotted and served via embedded Gitea +- No risk of corrupting your global installation +- Tests exactly what will happen when changes are pushed +- See `@shadow:context/shadow-instructions.md` for full documentation + +### Project-Local Virtual Environments + +When developing on Amplifier ecosystem repos directly: + +```bash +cd amplifier-core +python -m venv .venv +source .venv/bin/activate +pip install -e ".[dev]" +pytest tests/ +``` + +**Why project-local venv:** +- Isolated from other projects and global install +- Matches CI environment +- Easy to recreate +- Changes don't affect the installed CLI + +## Summary: Where Things Belong + +| What | Where | Why | +|------|-------|-----| +| Code you're modifying | Cloned repo or submodule | Git-tracked, pushable | +| Local source overrides | `.amplifier/settings.yaml` | Project-scoped, explicit | +| Dev dependencies | `.venv/` in the repo | Isolated, reproducible | +| Isolated testing | Shadow environment | Complete isolation | +| Installed CLI runtime | `~/.amplifier/cache/` | Auto-managed, don't touch | +| Clearing cache | `amplifier reset` | Handles reinstall safely | +| **NEVER** | Direct `rm -rf ~/.amplifier/cache/` | Breaks CLI |