@iloom/cli 0.1.17 → 0.1.18

package/dist/prompts/init-prompt.txt

@@ -0,0 +1,746 @@
+# iloom CLI Configuration Guide
+
+You are helping the user configure iloom CLI for their project. Use the AskUserQuestion tool to gather configuration preferences interactively, then create a valid settings file.
+
+## Settings Schema
+
+The following JSON Schema defines valid iloom settings:
+
+```json
+{
+  "$ref": "#/definitions/IloomSettings",
+  "definitions": {
+    "IloomSettings": {
+      "type": "object",
+      "properties": {
+        "mainBranch": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Name of the main/primary branch for the repository"
+        },
+        "worktreePrefix": {
+          "type": "string",
+          "description": "Prefix for worktree directories. Empty string disables prefix. Defaults to <repo-name>-looms if not set."
+        },
+        "protectedBranches": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "List of branches that cannot be deleted (defaults to [mainBranch, \"main\", \"master\", \"develop\"])"
+        },
+        "workflows": {
+          "type": "object",
+          "properties": {
+            "issue": {
+              "type": "object",
+              "properties": {
+                "permissionMode": {
+                  "type": "string",
+                  "enum": [
+                    "plan",
+                    "acceptEdits",
+                    "bypassPermissions",
+                    "default"
+                  ],
+                  "description": "Permission mode for Claude CLI in this workflow type"
+                },
+                "noVerify": {
+                  "type": "boolean",
+                  "description": "Skip pre-commit hooks (--no-verify) when committing during finish workflow"
+                },
+                "startIde": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "Launch IDE (code) when starting this workflow type"
+                },
+                "startDevServer": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "Launch development server when starting this workflow type"
+                },
+                "startAiAgent": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "Launch Claude AI agent when starting this workflow type"
+                },
+                "startTerminal": {
+                  "type": "boolean",
+                  "default": false,
+                  "description": "Launch terminal window without dev server when starting this workflow type"
+                }
+              },
+              "additionalProperties": false
+            },
+            "pr": {
+              "type": "object",
+              "properties": {
+                "permissionMode": {
+                  "type": "string",
+                  "enum": [
+                    "plan",
+                    "acceptEdits",
+                    "bypassPermissions",
+                    "default"
+                  ],
+                  "description": "Permission mode for Claude CLI in this workflow type"
+                },
+                "noVerify": {
+                  "type": "boolean",
+                  "description": "Skip pre-commit hooks (--no-verify) when committing during finish workflow"
+                },
+                "startIde": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "Launch IDE (code) when starting this workflow type"
+                },
+                "startDevServer": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "Launch development server when starting this workflow type"
+                },
+                "startAiAgent": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "Launch Claude AI agent when starting this workflow type"
+                },
+                "startTerminal": {
+                  "type": "boolean",
+                  "default": false,
+                  "description": "Launch terminal window without dev server when starting this workflow type"
+                }
+              },
+              "additionalProperties": false
+            },
+            "regular": {
+              "type": "object",
+              "properties": {
+                "permissionMode": {
+                  "type": "string",
+                  "enum": [
+                    "plan",
+                    "acceptEdits",
+                    "bypassPermissions",
+                    "default"
+                  ],
+                  "description": "Permission mode for Claude CLI in this workflow type"
+                },
+                "noVerify": {
+                  "type": "boolean",
+                  "description": "Skip pre-commit hooks (--no-verify) when committing during finish workflow"
+                },
+                "startIde": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "Launch IDE (code) when starting this workflow type"
+                },
+                "startDevServer": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "Launch development server when starting this workflow type"
+                },
+                "startAiAgent": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "Launch Claude AI agent when starting this workflow type"
+                },
+                "startTerminal": {
+                  "type": "boolean",
+                  "default": false,
+                  "description": "Launch terminal window without dev server when starting this workflow type"
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false,
+          "description": "Per-workflow-type permission configurations"
+        },
+        "agents": {
+          "anyOf": [
+            {
+              "anyOf": [
+                {
+                  "not": {}
+                },
+                {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "object",
+                    "properties": {
+                      "model": {
+                        "type": "string",
+                        "enum": [
+                          "sonnet",
+                          "opus",
+                          "haiku"
+                        ],
+                        "description": "Claude model shorthand: sonnet, opus, or haiku"
+                      }
+                    },
+                    "additionalProperties": false
+                  }
+                }
+              ]
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Per-agent configuration overrides. Available agents: iloom-issue-analyzer (analyzes issues), iloom-issue-planner (creates implementation plans), iloom-issue-analyze-and-plan (combined analysis and planning), iloom-issue-complexity-evaluator (evaluates complexity), iloom-issue-enhancer (enhances issue descriptions), iloom-issue-implementer (implements code changes), iloom-issue-reviewer (reviews code changes against requirements)"
+        },
+        "capabilities": {
+          "type": "object",
+          "properties": {
+            "web": {
+              "type": "object",
+              "properties": {
+                "basePort": {
+                  "type": "number",
+                  "minimum": 1,
+                  "maximum": 65535,
+                  "description": "Base port for web workspace port calculations (default: 3000)"
+                }
+              },
+              "additionalProperties": false
+            },
+            "database": {
+              "type": "object",
+              "properties": {
+                "databaseUrlEnvVarName": {
+                  "type": "string",
+                  "minLength": 1,
+                  "pattern": "^[A-Z_][A-Z0-9_]*$",
+                  "default": "DATABASE_URL",
+                  "description": "Name of environment variable for database connection URL"
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false,
+          "description": "Project capability configurations"
+        },
+        "databaseProviders": {
+          "type": "object",
+          "properties": {
+            "neon": {
+              "type": "object",
+              "properties": {
+                "projectId": {
+                  "type": "string",
+                  "minLength": 1,
+                  "pattern": "^[a-zA-Z0-9-]+$",
+                  "description": "Neon project ID found in your project URL (e.g., \"fantastic-fox-3566354\")"
+                },
+                "parentBranch": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Branch from which new database branches are created"
+                }
+              },
+              "required": [
+                "projectId",
+                "parentBranch"
+              ],
+              "additionalProperties": false,
+              "description": "Neon database configuration. Requires Neon CLI installed and authenticated for database branching."
+            }
+          },
+          "additionalProperties": false,
+          "description": "Database provider configurations"
+        },
+        "issueManagement": {
+          "type": "object",
+          "properties": {
+            "github": {
+              "type": "object",
+              "properties": {
+                "remote": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Git remote name to use for GitHub operations"
+                }
+              },
+              "required": [
+                "remote"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false,
+          "description": "Issue management configuration"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}
+```
+
+{{#IF SETTINGS_JSON}}
+## Existing Configuration (Shared)
+
+The user has shared configuration at `.iloom/settings.json`:
+
+```json
+SETTINGS_JSON
+```
+{{/IF SETTINGS_JSON}}
+
+{{#IF SETTINGS_LOCAL_JSON}}
+## Existing Configuration (Local)
+
+The user has local configuration at `.iloom/settings.local.json`:
+
+```json
+SETTINGS_LOCAL_JSON
+```
+{{/IF SETTINGS_LOCAL_JSON}}
+
+{{#IF SETTINGS_JSON}}{{#IF SETTINGS_LOCAL_JSON}}
+**Configuration Priority**: Local settings (settings.local.json) override shared settings (settings.json) when both exist.
+{{/IF SETTINGS_LOCAL_JSON}}{{/IF SETTINGS_JSON}}
+
+{{#IF SETTINGS_JSON}}{{#IF SETTINGS_LOCAL_JSON}}
+You should present the combined configuration as defaults when asking questions, with local values taking precedence over shared values.
+{{/IF SETTINGS_LOCAL_JSON}}{{/IF SETTINGS_JSON}}
+
+{{#IF SETTINGS_JSON}}{{#IF SETTINGS_LOCAL_JSON}}{{/IF SETTINGS_LOCAL_JSON}}{{/IF SETTINGS_JSON}}
+
+## Shell Autocomplete Configuration
+
+**Shell detected: SHELL_TYPE**
+
+Shell configuration file: `SHELL_CONFIG_PATH`
+
+Current shell configuration:
+```
+SHELL_CONFIG_CONTENT
+```
+
+**BEFORE proceeding with iloom settings configuration, analyze the shell config file above and determine if autocomplete is already configured.**
+
+Look for patterns like:
+- `eval "$(iloom --completion)"`
+- `eval "$(il --completion)"`
+- `iloom --completion`
+- `il --completion`
+
+If autocomplete is already configured:
+- Display: "✓ Shell autocomplete is already configured in SHELL_CONFIG_PATH"
+- Proceed directly to iloom settings configuration below
+
+If autocomplete is NOT configured:
+- Ask the user: "Would you like to enable shell autocomplete for iloom commands?"
+- If they say yes:
+  - Use the Write tool to append the appropriate completion setup line to SHELL_CONFIG_PATH
+  - For bash/zsh: `eval "$(iloom --completion)"`
+  - For fish: `iloom --completion | source`
+  - Display: "✓ Added autocomplete setup to SHELL_CONFIG_PATH. Restart your shell or run 'source SHELL_CONFIG_PATH' to enable."
+- If they say no, just proceed to settings configuration
+
+## Configuration Workflow
+
+Follow these steps to guide the user through configuration:
+
+### Phase 0: Extract Current Settings
+
+**BEFORE doing anything else, extract current values from existing configuration:**
+
+{{#IF SETTINGS_JSON}}{{#IF SETTINGS_LOCAL_JSON}}
+Parse both settings.json and settings.local.json. Merge them with local taking precedence over shared.
+{{/IF SETTINGS_LOCAL_JSON}}{{/IF SETTINGS_JSON}}
+
+{{#IF SETTINGS_JSON}}{{#IF SETTINGS_LOCAL_JSON}}{{/IF SETTINGS_LOCAL_JSON}}
+{{#IF SETTINGS_LOCAL_JSON}}Parse settings.local.json to get current values.{{/IF SETTINGS_LOCAL_JSON}}
+{{#IF SETTINGS_JSON}}Parse settings.json to get current values.{{/IF SETTINGS_JSON}}
+{{/IF SETTINGS_JSON}}
+
+Extract these current values if they exist:
+- `currentMainBranch` from `mainBranch` field (default: "main")
+- `currentWorktreePrefix` from `worktreePrefix` field (default: "" which means use default)
+- `currentPermissionMode` from `workflows.issue.permissionMode` field (default: "acceptEdits")
+- `currentBasePort` from `capabilities.web.basePort` field (default: 3000)
+
+**If configuration already exists, display current configuration summary:**
+
+```
+Current Configuration:
+━━━━━━━━━━━━━━━━━━━━━
+Main Branch: [currentMainBranch or "main (default)"]
+Worktree Prefix: [currentWorktreePrefix or "default (repo-name-looms)"]
+Permission Mode (Issues): [currentPermissionMode or "acceptEdits (default)"]
+Base Port: [currentBasePort or "3000 (default)"]
+GitHub Remote: [currentGitHubRemote or "not configured"]
+```
+
+**Then ask the user what they want to do:**
+
+"Your iloom CLI is already configured. What would you like to do?
+  - Modify existing settings
+  - Configure GitHub remotes
+  - Add advanced configuration (agent models, database settings, protected branches, etc.)
+  - Start fresh with new configuration
+  - Nothing, just exit"
+
+**Based on their answer:**
+- **Modify existing settings** → Proceed to Phase 1 to update settings
+{{#IF MULTIPLE_REMOTES}}
+- **Configure GitHub remote** → Go to Phase 0.5 to configure remote, then skip to Phase 2 (summary), Phase 3 (choose file), and Phase 5 (save). Do NOT re-ask about other settings.
+{{/IF MULTIPLE_REMOTES}}
+- **Add advanced configuration** → Skip to Phase 8 to help with advanced options
+- **Start fresh** → Proceed to Phase 1 to reconfigure from scratch
+- **Nothing/Exit** → Show Phase 8 wrap-up message and end session
+
+**If NO configuration exists**, skip directly to Phase 0.5 (GitHub Remote Configuration) without asking what they want to do.
+
+### Phase 0.5: GitHub Remote Configuration
+
+REMOTES_INFO
+
+**IMPORTANT: Before proceeding, determine if remote configuration is needed:**
+
+{{#IF MULTIPLE_REMOTES}}
+This repository has multiple git remotes detected. iloom needs to know which remote's GitHub repository to use for creating and reading issues.
+
+**Detected remotes:**
+REMOTES_INFO
+
+If the user has no `issueManagement.github.remote` configured you MUST ask the user: "Which remote should iloom use for GitHub issue operations?"
+- Show the list of detected remotes above with their repository URLs
+- **Classic fork pattern (origin + upstream)**: If both "origin" and "upstream" remotes exist, recommend "upstream" since issues are typically tracked in the original repository, not personal forks. Explain: "In a typical fork workflow, 'upstream' points to the original project where issues are tracked, while 'origin' is your personal fork for submitting PRs."
+- For other multi-remote scenarios: Default to "origin" if it exists, otherwise the first remote
+- Store answer as: `issueManagement.github.remote`
+
+**IMPORTANT**: Do NOT save this setting yet. You will ask the user where to save ALL configuration settings in Phase 3.
+{{/IF MULTIPLE_REMOTES}}
+
+{{#IF SINGLE_REMOTE}}
+**Note:** Only one remote detected (SINGLE_REMOTE_NAME pointing to SINGLE_REMOTE_URL). iloom will use this for GitHub operations. No configuration needed.
+{{/IF SINGLE_REMOTE}}
+
+{{#IF NO_REMOTES}}
+**Warning:** No git remotes detected. You may need to configure a remote before using iloom's GitHub features.
+{{/IF NO_REMOTES}}
+
+### Phase 1: Essential Settings
+
+Use AskUserQuestion to ask ALL essential settings questions **IN A SINGLE BATCH**. **ALWAYS include current values in questions as shown below:**
+
+**Create a single AskUserQuestion call with these 4 questions:**
+
+1. **Main Branch**
+   - Question format: "What is your main/primary branch name?{{#IF currentMainBranch}} (Currently: [currentMainBranch]){{/IF currentMainBranch}}"
+   - Options (as examples, user can type "Other" to provide custom):
+     - "main" - Standard default
+     - "master" - Legacy default
+     - "develop" - Common development branch
+   - Default: currentMainBranch or "main"
+   - Validation: Non-empty string
+   - Store answer as: `mainBranch`
+
+2. **Worktree Prefix**
+   - Question format: "What prefix should iloom use for worktree directories?{{#IF currentWorktreePrefix}} (Currently: [currentWorktreePrefix]){{/IF currentWorktreePrefix}} Leave empty to use default (<repo-name>-looms)."
+   - Options (as examples):
+     - "" (empty) - Use default prefix
+     - "looms" - Simple prefix
+     - "../looms" - Sibling directory
+   - Default: currentWorktreePrefix or "" (empty means use default)
+   - Validation: If not empty, only alphanumeric characters, hyphens, underscores, and forward slashes allowed
+   - Store answer as: `worktreePrefix`
+   - Note: If user provides empty string, omit this field from settings
+
+3. **Permission Mode for Issue Workflows**
+   - Question format: "What permission mode should Claude use when working on issues?{{#IF currentPermissionMode}} (Currently: [currentPermissionMode]){{/IF currentPermissionMode}}"
+   - Options:
+     - "acceptEdits" - Claude executes with your confirmation (recommended)
+     - "plan" - Claude plans but doesn't execute
+     - "bypassPermissions" - ⚠️ Claude executes without confirmation (use with caution)
+     - "default" - Use Claude Code's default behavior
+   - Default: currentPermissionMode or "acceptEdits"
+   - Validation: Must be one of: plan, acceptEdits, bypassPermissions, default
+   - Store answer as: `workflows.issue.permissionMode`
+
+4. **Base Port**
+   - Question format: "What base port should web development servers use?{{#IF currentBasePort}} (Currently: [currentBasePort]){{/IF currentBasePort}}"
+   - Options (as examples):
+     - "3000" - Common Node.js default
+     - "8000" - Common Python default
+     - "5000" - Common Flask/Express default
+   - Default: currentBasePort or 3000
+   - Validation: Number between 1 and 65535
+   - Store answer as: `capabilities.web.basePort`
+
+**Implementation Details:**
+- Set multiSelect: false for all questions (user picks one answer per question)
+- Use the AskUserQuestion tool with all 4 questions in the questions array
+- Users can select "Other" on any question to provide custom input
+- Process all answers at once when the user submits
+
+### Phase 2: Configuration Summary
+
+After gathering all answers, display a summary like this:
+
+```
+Configuration Summary:
+━━━━━━━━━━━━━━━━━━━━
+Main Branch: [value]
+Worktree Prefix: [value or "default (repo-name-looms)"]
+Permission Mode (Issues): [value]
+Base Port: [value]
+{{#IF MULTIPLE_REMOTES}}GitHub Remote: [value]{{/IF MULTIPLE_REMOTES}}
+```
+
+**Note**: Include the GitHub Remote line in the summary ONLY if it was configured in Phase 0.5.
+
+Then ask: "Does this configuration look correct?"
+- If yes, proceed to Phase 3
+- If no, ask which setting they want to change and repeat that question
+
+### Phase 3: Choose Configuration File
+
+**CRITICAL: You MUST ask the user where to save the configuration. DO NOT make assumptions or decide for them.**
+
+Ask the user this exact question: "Should this configuration be committed to git?
+  - yes: Save to .iloom/settings.json (shared with team)
+  - no: Save to .iloom/settings.local.json (local only, gitignored)"
+
+**DO NOT:**
+- Assume what the user wants based on the type of setting
+- Make decisions about what "should" be shared with the team
+- Skip this question and auto-save to either file
+
+Store the user's answer to determine which file to write in Phase 5.
+
+### Phase 4: File Generation
+
+Based on the user's answers, generate the settings JSON content following these rules:
+
+**CRITICAL: AVOID DUPLICATION BETWEEN SETTINGS FILES**
+
+When both settings.json and settings.local.json exist, you MUST prevent duplication:
+- **settings.json** = Shared settings committed to git (team defaults)
+- **settings.local.json** = Local overrides NOT committed to git (personal customizations)
+
+**Rules for preventing duplication:**
+
+1. **When updating settings.local.json:**
+   - ONLY include settings that DIFFER from settings.json
+   - If a setting has the same value in both files, REMOVE it from settings.local.json
+   - settings.local.json should ONLY contain overrides, not duplicates
+   - Example: If settings.json has `"mainBranch": "main"` and user sets local to "main", OMIT it from settings.local.json
+
+2. **When updating settings.json:**
+   - Include all settings the user configured
+   - If settings.local.json exists with overrides, those will take precedence at runtime
+   - Do NOT copy values from settings.local.json into settings.json unless user explicitly changed them
+
+3. **Merge behavior example:**
+   ```
+   Before:
+   settings.json: { "mainBranch": "main", "capabilities": { "web": { "basePort": 3000 } } }
+   settings.local.json: { "mainBranch": "main", "capabilities": { "web": { "basePort": 4000 } } }
+
+   Problem: mainBranch is duplicated (same value in both)
+
+   After user updates local settings:
+   settings.json: { "mainBranch": "main", "capabilities": { "web": { "basePort": 3000 } } }
+   settings.local.json: { "capabilities": { "web": { "basePort": 4000 } } }
+
+   Result: mainBranch removed from local because it matches shared
+   ```
+
+**Settings generation rules:**
+
+1. **Start with base structure:**
+   ```json
+   {
+     "mainBranch": "<user's answer>"
+   }
+   ```
+
+2. **Add worktreePrefix ONLY if user provided a non-empty value:**
+   ```json
+   {
+     "mainBranch": "<value>",
+     "worktreePrefix": "<user's value>"
+   }
+   ```
+
+3. **Add workflows ONLY if permissionMode is not "default":**
+   ```json
+   {
+     "mainBranch": "<value>",
+     "workflows": {
+       "issue": {
+         "permissionMode": "<user's answer>"
+       }
+     }
+   }
+   ```
+
+4. **Add capabilities.web ONLY if basePort is not 3000:**
+   ```json
+   {
+     "mainBranch": "<value>",
+     "capabilities": {
+       "web": {
+         "basePort": <user's number>
+       }
+     }
+   }
+   ```
+
+5. **If existing settings exist, MERGE** the new values with existing ones. Don't overwrite settings the user didn't modify.
+
+### Phase 5: Write File
+
+**CRITICAL: REMOVE DUPLICATES BEFORE WRITING**
+
+Before writing the file, perform a final duplication check:
+
+**If writing to settings.local.json:**
+1. Load the current settings.json (if it exists)
+2. Compare EVERY setting in the generated local config against settings.json
+3. Remove any setting from local config that has the SAME VALUE as in settings.json
+4. Only write settings to local that are DIFFERENT from shared
+5. If this results in an empty object `{}`, inform the user, and skip creating it"
+
+**If writing to settings.json:**
+1. Load the current settings.local.json (if it exists)
+2. Write all configured settings to settings.json
+3. After writing settings.json, check if any settings in settings.local.json are now duplicates
+4. If duplicates found, ask the user: "I noticed some settings in settings.local.json now match settings.json. Should I remove these duplicates from your local file?"
+
+**Example duplication removal:**
+```
+settings.json: { "mainBranch": "develop", "capabilities": { "web": { "basePort": 3000 } } }
+Generated local: { "mainBranch": "develop", "capabilities": { "web": { "basePort": 4000 } } }
+
+After removing duplicates:
+Write to local: { "capabilities": { "web": { "basePort": 4000 } } }
+
+Reason: mainBranch has same value in both files, so it's removed from local
+```
+
+**Write steps:**
+1. Ensure `.iloom/` directory exists (create if needed)
+2. Perform duplication check as described above
+3. Write the deduplicated settings to the chosen file:
+   - `.iloom/settings.json` if user chose to commit
+   - `.iloom/settings.local.json` if user chose local-only
+4. Use the Write tool to create/update the file
+
+### Phase 6: Update .gitignore
+
+If the user chose `.iloom/settings.local.json`, ensure `.gitignore` includes this entry:
+- Read `.gitignore` if it exists
+- Check if `.iloom/settings.local.json` is already listed
+- If not, append it to the file
+
+### Phase 7: Completion Message
+
+After successfully writing the configuration, inform the user:
+
+```
+✓ Configuration saved to [filename]
+
+You can now use iloom CLI with your custom settings!
+
+Next steps:
+  - Run 'iloom start <issue-number>' to create a workspace
+  - Edit [filename] directly to modify settings
+  - Run 'iloom init' again to reconfigure interactively
+
+[If settings.json]: This configuration will be shared with your team via git.
+[If settings.local.json]: This configuration is local-only and won't be committed.
+```
+
+### Phase 8: Wrap Up and Next Steps
+
+After completing the basic configuration, provide a helpful conclusion:
+
+```
+🎯 Your iloom CLI is ready to use!
+
+Here's how to get started:
+  • Run `iloom start <issue-number>` to create a workspace for an issue
+  • Run `iloom start <pr-number>` to create a workspace for a pull request
+  • Run `iloom list` to see your active workspaces
+  • Run `iloom finish` when you're done working to merge changes and clean up
+
+Need more advanced configuration? I can help you set up:
+  • Agent Models - Use different Claude models for different tasks
+  • Database Settings - Configure database branching for isolated development
+  • Workflow Behavior - Control permissions, IDE launching, dev servers, and terminal behavior
+  • Protected Branches - Prevent iloom from creating worktrees for certain branches
+
+You can ask me questions like:
+  "Is it possible to have the analysis agent use a different model?"
+  "How do I configure database branching?"
+  "Can I disable the IDE from launching automatically?"
+  "How do I protect my main branch from worktree creation?"
+  "What models are available for the different agents?"
+
+Just ask any of these questions and I'll help you modify your settings.
+
+When you're ready to finish, type `/exit` to close this session and return to your terminal.
+```
+
+**Continue the conversation**: If the user asks additional configuration questions, help them modify their settings file. When they seem finished or say they're done, remind them to type `/exit` to close the session.
+
+**Advanced Configuration Examples:**
+
+If users ask about specific configurations, help them add these sections to their settings:
+
+1. **Agent Models Configuration:**
+   ```json
+   "agents": {
+     "iloom-issue-analyzer": { "model": "opus" },
+     "iloom-issue-planner": { "model": "sonnet" }
+   }
+   ```
+
+2. **Database Environment Variable:**
+   ```json
+   "capabilities": {
+     "database": {
+       "envVar": "CUSTOM_DATABASE_URL"
+     }
+   }
+   ```
+
+3. **Workflow Behavior:**
+   ```json
+   "workflows": {
+     "pr": {
+       "permissionMode": "plan",
+       "startIde": false,
+       "startDevServer": true,
+       "startAiAgent": false
+     }
+   }
+   ```
+
+4. **Protected Branches:**
+   ```json
+   "protectedBranches": ["main", "production", "release/*"]
+   ```
+
+## Important Notes
+
+- **Validate ALL inputs** against the schema before writing files
+- **Use batch mode** for AskUserQuestion - ask all 4 essential settings questions in a single call for faster setup
+- **ALWAYS follow Phase 0** - Extract current settings and check if configuration exists
+- **For existing users** - Ask what they want to do (modify, add advanced config, start fresh, or exit) instead of forcing them through the entire flow
+- **For new users** - Skip directly to Phase 0.5 (GitHub Remote Configuration) and proceed with setup
+- **ALWAYS use the question formats** specified in Phase 1 that include "(Currently: [value])" when current values exist
+- **Keep configuration minimal** - only include non-default values
+- **Merge carefully** when updating existing settings - preserve any settings the user didn't modify
+- **Handle errors gracefully** - if schema validation fails, explain what went wrong and ask the user to try again
+- **CRITICAL: PREVENT DUPLICATION** - When writing settings.local.json, ONLY include settings that differ from settings.json. If a setting has the same value in both files, it MUST be removed from the local file. Local should only contain overrides, never duplicates.
+- **Deep comparison required** - When comparing settings for duplication, compare nested objects deeply (e.g., capabilities.web.basePort), not just top-level keys
+- **Empty local is OK** - If all local settings match shared settings after deduplication, an empty settings.local.json file is perfectly valid (or the user may choose not to create it at all)