Merge PR microsoft#44 - AI-First Principles and PR microsoft#7 - Global Amplifier access

Author: Claude

.claude/settings.json

@@ -14,7 +14,7 @@
       ".vscode",
       ".claude",
       ".ai",
-      "~/amplifier"
+      "~/dev/amplifier"
     ]
   },
   "enableAllProjectMcpServers": false,

.gitignore

@@ -18,7 +18,8 @@ __pycache__
 .ruff_cache
 .cache
 *.egg-info
-bin
+# bin directory for build artifacts (but allow our global command)
+# bin
 obj
 dist
 build

Makefile

@@ -21,6 +21,7 @@ default: ## Show essential commands
 	@echo ""
 	@echo "Quick Start:"
 	@echo "  make install         Install all dependencies"
+	@echo "  make install-global  Install global 'amplifier' command"
 	@echo ""
 	@echo "Knowledge Base:"
 	@echo "  make knowledge-update        Full pipeline: extract & synthesize"
@@ -74,6 +75,7 @@ help: ## Show ALL available commands
 	@echo ""
 	@echo "QUICK START:"
 	@echo "  make install         Install all dependencies"
+	@echo "  make install-global  Install global 'amplifier' command"
 	@echo ""
 	@echo "KNOWLEDGE BASE:"
 	@echo "  make knowledge-update        Full pipeline: extract & synthesize"
@@ -165,6 +167,9 @@ install: ## Install all dependencies
 	@echo ""
 	@echo "✅ All dependencies installed!"
 	@echo ""
+	@echo "💡 For global access to Amplifier from any directory:"
+	@echo "   make install-global"
+	@echo ""
 	@if [ -n "$$VIRTUAL_ENV" ]; then \
 		echo "✓ Virtual environment already active"; \
 	elif [ -f .venv/bin/activate ]; then \
@@ -173,6 +178,67 @@ install: ## Install all dependencies
 		echo "✗ No virtual environment found. Run 'make install' first."; \
 	fi
 
+# Global installation
+install-global: ## Install global 'amplifier' command for system-wide access
+	@echo "Installing global Amplifier command..."
+	@if [ ! -f .venv/bin/activate ]; then \
+		echo "❌ Please run 'make install' first to create the virtual environment"; \
+		exit 1; \
+	fi
+	@mkdir -p ~/bin
+	@cp bin/amplifier ~/bin/amplifier
+	@chmod +x ~/bin/amplifier
+	@echo "✅ Global 'amplifier' command installed to ~/bin/amplifier"
+	@echo ""
+	@if echo "$$PATH" | grep -q "$$HOME/bin"; then \
+		echo "✓ ~/bin is already in your PATH"; \
+	else \
+		echo "💡 Add ~/bin to your PATH for global access:"; \
+		if [ -n "$$ZSH_VERSION" ] || [ "$$SHELL" = "/bin/zsh" ] || [ -f ~/.zshrc ]; then \
+			echo '   echo "export PATH="\$$HOME/bin:\$$PATH"" >> ~/.zshrc'; \
+			echo "   source ~/.zshrc"; \
+		else \
+			echo '   echo "export PATH="\$$HOME/bin:\$$PATH"" >> ~/.bashrc'; \
+			echo "   source ~/.bashrc"; \
+		fi; \
+	fi
+	@echo ""
+	@echo "Usage: amplifier [project-dir] [claude-options]"
+	@echo "Example: amplifier ~/my-project --model sonnet"
+
+install-global-system: ## Install global 'amplifier' command system-wide (requires sudo)
+	@echo "Installing system-wide Amplifier command..."
+	@if [ ! -f .venv/bin/activate ]; then \
+		echo "❌ Please run 'make install' first to create the virtual environment"; \
+		exit 1; \
+	fi
+	@echo "This will install to /usr/local/bin and requires sudo privileges."
+	@read -p "Continue? [y/N] " -n 1 -r; echo; \
+	if [[ $$REPLY =~ ^[Yy]$$ ]]; then \
+		sudo cp bin/amplifier /usr/local/bin/amplifier; \
+		sudo chmod +x /usr/local/bin/amplifier; \
+		echo "✅ Global 'amplifier' command installed to /usr/local/bin/amplifier"; \
+	else \
+		echo "Installation cancelled."; \
+	fi
+
+uninstall-global: ## Remove global 'amplifier' command
+	@echo "Removing global Amplifier command..."
+	@if [ -f ~/bin/amplifier ]; then \
+		rm ~/bin/amplifier; \
+		echo "✅ Removed ~/bin/amplifier"; \
+	else \
+		echo "✓ ~/bin/amplifier not found"; \
+	fi
+	@if [ -f /usr/local/bin/amplifier ]; then \
+		echo "System-wide installation found at /usr/local/bin/amplifier"; \
+		read -p "Remove it? (requires sudo) [y/N] " -n 1 -r; echo; \
+		if [[ $$REPLY =~ ^[Yy]$$ ]]; then \
+			sudo rm /usr/local/bin/amplifier; \
+			echo "✅ Removed /usr/local/bin/amplifier"; \
+		fi; \
+	fi
+
 # Code quality
 check: ## Format, lint, and type-check all code
 	@# Handle worktree virtual environment issues by unsetting mismatched VIRTUAL_ENV

README.md

@@ -123,20 +123,131 @@ We've taken our learnings about what works in AI-assisted development and packag
 
 ---
 
+5. **Install global access** (Optional but recommended):
+   ```bash
+   make install-global
+   ```
+   
+   This installs the `amplifier` command globally, letting you use Amplifier on any project from anywhere:
+   
+   ```bash
+   cd ~/my-other-project
+   amplifier  # Starts Claude with Amplifier agents for this project
+   ```
+
 ## 📖 How to Use Amplifier
 
 ### Create Amplifier-powered Tools for Scenarios
 
 Amplifier is designed so **you can create new AI-powered tools** just by describing how they should think. See the [Create Your Own Tools](docs/CREATE_YOUR_OWN_TOOLS.md) guide for more information.
 
-### Explore Ampifier's agents on your code
+### Explore Amplifier's Agents on Your Code
 
 Try out one of the specialized experts:
 
 - "Use the zen-architect agent to design my application's caching layer"
 - "Deploy bug-hunter to find why my login system is failing"
 - "Have security-guardian review my API implementation for vulnerabilities"
 
+### Global Usage: Amplifier on Any Project 🌍
+
+**The power of Amplifier is no longer confined to the Amplifier directory.** Use all 20+ specialized agents, knowledge extraction, and automation tools on any codebase, anywhere on your system.
+
+#### Method 1: Global Command (Recommended)
+
+After running `make install-global`, use Amplifier from any directory:
+
+```bash
+# Work on any project
+cd ~/my-web-app
+amplifier
+
+# Or specify a different project
+amplifier ~/dev/my-python-api
+
+# Pass Claude options
+amplifier ~/my-project --model sonnet
+amplifier ~/my-app --print "Fix the authentication bug"
+```
+
+#### Method 2: From Amplifier Directory
+
+If you prefer not to install globally:
+
+```bash
+cd ~/dev/amplifier
+./amplifier-anywhere.sh ~/path/to/your/project
+
+# Or with Claude options
+./amplifier-anywhere.sh ~/my-app --model sonnet
+```
+
+#### Method 3: Manual Setup
+
+For maximum control:
+
+```bash
+cd ~/dev/amplifier
+source .venv/bin/activate
+claude --add-dir /path/to/your/project
+```
+
+#### Usage Template
+
+**Important**: When Claude starts, always begin with this message template:
+
+```
+I'm working in [YOUR_PROJECT_PATH] which doesn't have Amplifier files.
+Please cd to that directory and work there.
+Do NOT update any issues or PRs in the Amplifier repo.
+
+Use [AGENT_NAME] to [TASK_DESCRIPTION].
+```
+
+**Examples**:
+- `"Use zen-architect to design my application's caching layer"`
+- `"Deploy bug-hunter to find why my login system is failing"`
+- `"Have security-guardian review my API implementation for vulnerabilities"`
+- `"Use modular-builder to implement the user profile feature"`
+
+#### Global Benefits
+
+✅ **All 20+ specialized agents** work on your projects
+✅ **Shared knowledge base** - insights from one project help others
+✅ **Same powerful automation** - quality checks, parallel development
+✅ **Project isolation** - changes only affect your target project
+✅ **Works anywhere** - no need to copy files or modify your projects
+
+#### Troubleshooting Global Access
+
+**Command not found: `amplifier`**
+```bash
+# Check if ~/bin is in PATH
+echo $PATH | grep $HOME/bin
+
+# Add to PATH if missing
+echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc  # or ~/.bashrc
+source ~/.zshrc
+```
+
+**Cannot find Amplifier installation**
+```bash
+# The global command looks for Amplifier in these locations:
+# - ~/dev/amplifier (most common)
+# - ~/amplifier
+# - ~/repos/amplifier
+# - ~/code/amplifier
+
+# Create a symlink if needed
+ln -s /path/to/your/amplifier ~/dev/amplifier
+```
+
+**Get help anytime**
+```bash
+amplifier --help     # Show usage help
+amplifier --version  # Show version info
+```
+
 ### Parallel Development
 
 **Why use this?** Stop wondering "what if" — build multiple solutions simultaneously and pick the winner.