From 05cbc6ccb8674ed38fdbb404d0945022da36847b Mon Sep 17 00:00:00 2001
From: Brian Madison <brianmadison@Brians-MacBook-Pro.local>
Date: Sat, 22 Nov 2025 16:10:53 -0600
Subject: [PATCH] feat: rename agent-install parameters for clarity
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Change --path → --source (much clearer purpose)
- Change --target → --destination (more intuitive)
- Update all code references and documentation
- Add advanced parameter examples to installation guide
- Keep short aliases: -s for --source, -t for --destination

Parameters are now much more self-explanatory:
- --source: where to find the agent YAML
- --destination: where to install the compiled agent
---
 docs/custom-agent-installation.md                | 12 ++++++------
 .../workflows/create-agent/installation-guide.md | 16 ++++++++++++++++
 tools/cli/commands/agent-install.js              | 14 +++++++-------
 3 files changed, 29 insertions(+), 13 deletions(-)

diff --git a/docs/custom-agent-installation.md b/docs/custom-agent-installation.md
index 2cf89980..01bedcf4 100644
--- a/docs/custom-agent-installation.md
+++ b/docs/custom-agent-installation.md
@@ -37,20 +37,20 @@ Options:
 
 ## Installing from Custom Locations
 
-Use the `-p` / `--path` option to install agents from any location:
+Use the `-s` / `--source` option to install agents from any location:
 
 ```bash
 # Install agent from a custom folder (expert agent with sidecar)
-bmad agent-install -p path/to/my-agent
+bmad agent-install -s path/to/my-agent
 
 # Install a specific .agent.yaml file (simple agent)
-bmad agent-install -p path/to/my-agent.agent.yaml
+bmad agent-install -s path/to/my-agent.agent.yaml
 
 # Install with defaults (skip all prompts)
-bmad agent-install -p path/to/my-agent -d
+bmad agent-install -s path/to/my-agent -d
 
-# Install to a specific target project
-bmad agent-install -p path/to/my-agent -t /path/to/target/project
+# Install to a specific destination project
+bmad agent-install -s path/to/my-agent --destination /path/to/destination/project
 ```
 
 This is useful when:
diff --git a/src/modules/bmb/workflows/create-agent/installation-guide.md b/src/modules/bmb/workflows/create-agent/installation-guide.md
index 8aee19da..b9ab6c01 100644
--- a/src/modules/bmb/workflows/create-agent/installation-guide.md
+++ b/src/modules/bmb/workflows/create-agent/installation-guide.md
@@ -50,6 +50,22 @@ npx bmad-method agent-install    # Works anywhere without cloning
 - `bmad install` → "Compile Agents" (rebuild all agents)
 - `bmad install` → "Quick Update" (during upgrades)
 
+**Advanced Parameters**:
+
+```bash
+# Install specific agent file
+npx bmad-method agent-install --source ./my-agent.agent.yaml
+
+# Use default configuration (no prompts)
+npx bmad-method agent-install --defaults
+
+# Install to specific destination
+npx bmad-method agent-install --destination ./my-project
+
+# Combine parameters
+npx bmad-method agent-install --source ./my-agent.agent.yaml --defaults --destination ./my-project
+```
+
 **When to use which**:
 
 - **Option 1**: Best for new agents or when you want custom persona names
diff --git a/tools/cli/commands/agent-install.js b/tools/cli/commands/agent-install.js
index 031d40c2..57b0c8c1 100644
--- a/tools/cli/commands/agent-install.js
+++ b/tools/cli/commands/agent-install.js
@@ -22,9 +22,9 @@ module.exports = {
   command: 'agent-install',
   description: 'Install and compile BMAD agents with personalization',
   options: [
-    ['-p, --path <path>', 'Path to specific agent YAML file or folder'],
+    ['-s, --source <path>', 'Path to specific agent YAML file or folder'],
     ['-d, --defaults', 'Use default values without prompting'],
-    ['-t, --target <path>', 'Target installation directory (default: .bmad/agents)'],
+    ['-t, --destination <path>', 'Target installation directory (default: current project BMAD installation)'],
   ],
   action: async (options) => {
     try {
@@ -43,9 +43,9 @@ module.exports = {
 
       let selectedAgent = null;
 
-      // If path provided, use it directly
-      if (options.path) {
-        const providedPath = path.resolve(options.path);
+      // If source provided, use it directly
+      if (options.source) {
+        const providedPath = path.resolve(options.source);
 
         if (!fs.existsSync(providedPath)) {
           console.log(chalk.red(`Path not found: ${providedPath}`));
@@ -192,11 +192,11 @@ module.exports = {
       }
 
       // Determine target directory
-      let targetDir = options.target ? path.resolve(options.target) : null;
+      let targetDir = options.destination ? path.resolve(options.destination) : null;
 
       // If no target specified, prompt for it
       if (targetDir) {
-        // If target provided via --target, check if it's a project root and adjust
+        // If target provided via --destination, check if it's a project root and adjust
         const otherProject = detectBmadProject(targetDir);
         if (otherProject && !targetDir.includes('agents')) {
           // User specified project root, redirect to custom agents folder