@iloom/cli 0.9.2 → 0.10.1

package/dist/prompts/init-prompt.txt

@@ -304,6 +304,15 @@ The following JSON Schema defines valid iloom settings:
                         ],
                         "description": "Claude model shorthand: sonnet, opus, or haiku"
                       },
+                      "swarmModel": {
+                        "type": "string",
+                        "enum": [
+                          "sonnet",
+                          "opus",
+                          "haiku"
+                        ],
+                        "description": "Model to use for this agent in swarm mode. Overrides the base model when running inside swarm workers."
+                      },
                       "enabled": {
                         "type": "boolean",
                         "description": "Whether this agent is enabled. Defaults to true."
@@ -325,6 +334,63 @@ The following JSON Schema defines valid iloom settings:
                       "review": {
                         "type": "boolean",
                         "description": "Whether artifacts from this agent should be reviewed before posting (defaults to false)"
+                      },
+                      "agents": {
+                        "type": "object",
+                        "additionalProperties": {
+                          "type": "object",
+                          "properties": {
+                            "model": {
+                              "type": "string",
+                              "enum": [
+                                "sonnet",
+                                "opus",
+                                "haiku"
+                              ],
+                              "description": "Claude model shorthand: sonnet, opus, or haiku"
+                            },
+                            "swarmModel": {
+                              "type": "string",
+                              "enum": [
+                                "sonnet",
+                                "opus",
+                                "haiku"
+                              ],
+                              "description": "Model to use for this agent in swarm mode. Overrides the base model when running inside swarm workers."
+                            },
+                            "enabled": {
+                              "type": "boolean",
+                              "description": "Whether this agent is enabled. Defaults to true."
+                            },
+                            "providers": {
+                              "type": "object",
+                              "additionalProperties": {
+                                "type": "string"
+                              },
+                              "propertyNames": {
+                                "enum": [
+                                  "claude",
+                                  "gemini",
+                                  "codex"
+                                ]
+                              },
+                              "description": "Map of review providers to model names. Keys: claude, gemini, codex. Values: model name strings (e.g., \"sonnet\", \"gemini-3-pro-preview\", \"gpt-5.2-codex\")"
+                            },
+                            "review": {
+                              "type": "boolean",
+                              "description": "Whether artifacts from this agent should be reviewed before posting (defaults to false)"
+                            }
+                          },
+                          "additionalProperties": false
+                        },
+                        "description": "Nested per-agent settings. Only meaningful under the iloom-swarm-worker agent entry for sub-agent timeout configuration."
+                      },
+                      "subAgentTimeout": {
+                        "type": "number",
+                        "minimum": 1,
+                        "maximum": 120,
+                        "default": 10,
+                        "description": "Timeout in minutes for sub-agent claude -p invocations in swarm mode. Applies to each phase agent (evaluator, analyzer, planner, implementer) when invoked via the Bash tool. Default: 10 minutes. Only meaningful under the iloom-swarm-worker agent entry."
                       }
                     },
                     "additionalProperties": false
@@ -336,7 +402,7 @@ The following JSON Schema defines valid iloom settings:
               "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-code-reviewer (reviews code changes against requirements), iloom-artifact-reviewer (reviews artifacts before posting)"
+          "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-code-reviewer (reviews code changes against requirements), iloom-artifact-reviewer (reviews artifacts before posting), iloom-swarm-worker (swarm worker agent, dynamically generated). Use swarmModel on any agent to override its model in swarm mode."
         },
         "spin": {
           "type": "object",
@@ -350,6 +416,15 @@ The following JSON Schema defines valid iloom settings:
               ],
               "default": "opus",
               "description": "Claude model shorthand for spin orchestrator"
+            },
+            "swarmModel": {
+              "type": "string",
+              "enum": [
+                "sonnet",
+                "opus",
+                "haiku"
+              ],
+              "description": "Model for the spin orchestrator when running in swarm mode. Overrides spin.model for swarm workflows."
             }
           },
           "additionalProperties": false,
@@ -413,17 +488,6 @@ The following JSON Schema defines valid iloom settings:
         "capabilities": {
           "type": "object",
           "properties": {
-            "capabilities": {
-              "type": "array",
-              "items": {
-                "type": "string",
-                "enum": [
-                  "cli",
-                  "web"
-                ]
-              },
-              "description": "Explicitly declared project capabilities (auto-detected if not specified)"
-            },
             "web": {
               "type": "object",
               "properties": {
@@ -434,7 +498,8 @@ The following JSON Schema defines valid iloom settings:
                   "description": "Base port for web workspace port calculations (default: 3000)"
                 }
               },
-              "additionalProperties": false
+              "additionalProperties": false,
+              "description": "Web dev server settings. To declare a project as a web project, add \"web\" to the capabilities array in .iloom/package.iloom.json or .iloom/package.iloom.local.json."
             },
             "database": {
               "type": "object",
@@ -489,10 +554,11 @@ The following JSON Schema defines valid iloom settings:
               "type": "string",
               "enum": [
                 "github",
-                "linear"
+                "linear",
+                "jira"
               ],
               "default": "github",
-              "description": "Issue tracker provider (github, linear)"
+              "description": "Issue tracker provider (github, linear, jira)"
             },
             "github": {
               "type": "object",
@@ -529,6 +595,69 @@ The following JSON Schema defines valid iloom settings:
                 "teamId"
               ],
               "additionalProperties": false
+            },
+            "jira": {
+              "type": "object",
+              "properties": {
+                "host": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Jira instance URL (e.g., \"https://yourcompany.atlassian.net\")"
+                },
+                "username": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Jira username or email address"
+                },
+                "apiToken": {
+                  "type": "string",
+                  "description": "Jira API token. SECURITY: Store in settings.local.json only, never commit to source control. Generate at: https://id.atlassian.com/manage-profile/security/api-tokens"
+                },
+                "projectKey": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Jira project key (e.g., \"PROJ\", \"ENG\")"
+                },
+                "boardId": {
+                  "type": "string",
+                  "description": "Jira board ID for sprint/workflow operations (optional)"
+                },
+                "transitionMappings": {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string"
+                  },
+                  "description": "Map iloom states to Jira transition names (e.g., {\"In Review\": \"Start Review\"})"
+                },
+                "defaultIssueType": {
+                  "type": "string",
+                  "minLength": 1,
+                  "default": "Task",
+                  "description": "Default Jira issue type name for creating issues (e.g., \"Task\", \"Story\", \"Bug\")"
+                },
+                "defaultSubtaskType": {
+                  "type": "string",
+                  "minLength": 1,
+                  "default": "Subtask",
+                  "description": "Default Jira issue type name for creating subtasks/child issues (e.g., \"Subtask\", \"Sub-task\")"
+                },
+                "doneStatuses": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "default": [
+                    "Done"
+                  ],
+                  "description": "Status names to exclude from issue lists (e.g., [\"Done\", \"Closed\", \"Verify\"])"
+                }
+              },
+              "required": [
+                "host",
+                "username",
+                "projectKey"
+              ],
+              "additionalProperties": false
             }
           },
           "additionalProperties": false,
@@ -552,6 +681,11 @@ The following JSON Schema defines valid iloom settings:
             "autoCommitPush": {
               "type": "boolean",
               "description": "Auto-commit and push after code review in draft PR mode. Defaults to true when mode is github-draft-pr."
+            },
+            "openBrowserOnFinish": {
+              "type": "boolean",
+              "default": true,
+              "description": "Open the PR in the default browser after finishing in github-pr or github-draft-pr mode. Use --no-browser flag to override."
             }
           },
           "additionalProperties": false,
@@ -720,6 +854,10 @@ Extract these current values if they exist:
 - `currentIssueProvider` from `issueManagement.provider` field (default: "github")
 - `currentLinearTeamId` from `issueManagement.linear.teamId` field (if Linear is provider)
 - `currentGitHubRemote` from `issueManagement.github.remote` field (if GitHub is provider and multiple remotes)
+- `currentJiraHost` from `issueManagement.jira.host` field (if Jira is provider)
+- `currentJiraUsername` from `issueManagement.jira.username` field (if Jira is provider)
+- `currentJiraProjectKey` from `issueManagement.jira.projectKey` field (if Jira is provider)
+- `currentJiraBoardId` from `issueManagement.jira.boardId` field (if Jira is provider, optional)
 
 **If configuration already exists, display current configuration summary:**
 
@@ -733,6 +871,9 @@ IDE: [currentIdeType or "vscode (default)"]
 Issue Tracker: [currentIssueProvider or "github (default)"]
 Linear Team ID: [currentLinearTeamId] (only if currentIssueProvider == linear)
 {{#if MULTIPLE_REMOTES}}GitHub Remote: [currentGitHubRemote] (only if currentIssueProvider == github){{/if}}
+Jira Host: [currentJiraHost] (only if currentIssueProvider == jira)
+Jira Project Key: [currentJiraProjectKey] (only if currentIssueProvider == jira)
+Jira Board ID: [currentJiraBoardId] (only if currentIssueProvider == jira and boardId is set)
 ```
 
 **Then ask the user what they want to do:**
@@ -814,7 +955,69 @@ The agent will:
 4. Create `.iloom/package.iloom.json` with the detected configuration
 5. Detect and set project capabilities (cli, web) based on the framework
 
-**File Format:**
+**package.iloom.json Schema:**
+```json
+{
+  "$ref": "#/definitions/PackageIloom",
+  "definitions": {
+    "PackageIloom": {
+      "type": "object",
+      "properties": {
+        "capabilities": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "cli",
+              "web"
+            ]
+          },
+          "description": "Project capabilities - \"cli\" for command-line tools (enables CLI isolation), \"web\" for web applications (enables port assignment and dev server)"
+        },
+        "scripts": {
+          "type": "object",
+          "properties": {
+            "install": {
+              "type": "string",
+              "description": "Install command (e.g., \"bundle install\", \"poetry install\")"
+            },
+            "build": {
+              "type": "string",
+              "description": "Build/compile command"
+            },
+            "test": {
+              "type": "string",
+              "description": "Test suite command"
+            },
+            "dev": {
+              "type": "string",
+              "description": "Dev server command"
+            },
+            "lint": {
+              "type": "string",
+              "description": "Linting command"
+            },
+            "typecheck": {
+              "type": "string",
+              "description": "Type checking command"
+            },
+            "compile": {
+              "type": "string",
+              "description": "Compilation command (preferred over typecheck if both exist)"
+            }
+          },
+          "additionalProperties": false,
+          "description": "Custom shell commands for project operations. These are raw shell commands, not npm script names."
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}
+```
+
+**File Format Example:**
 ```json
 {
   "capabilities": ["cli"],
@@ -855,7 +1058,16 @@ If the framework detector did not set capabilities, or if you need to ask the us
   - "web" - Web application with dev server
   - "both" - Both CLI and web capabilities
   - "neither" - Library or other project type
-- Update `.iloom/package.iloom.json` with the appropriate `capabilities` array.
+
+**Choose where to save package.iloom configuration:**
+
+After determining the configuration, ask the user where to save it:
+- **Project** (`package.iloom.json`) - Shared with team, committed to git
+- **Local** (`package.iloom.local.json`) - Local only, gitignored, never committed
+
+Default to **Local** if fork was detected (origin + upstream remotes). Otherwise default to **Project**.
+
+Write the capabilities and scripts to the chosen file.
 
 **When to infer capabilities:**
 - Flask/Django/FastAPI/Rails/Actix/Rocket detected -> include "web"
@@ -873,7 +1085,7 @@ This phase configures external tooling integrations. Use AskUserQuestion to gath
 **Step 1: Issue Tracker Provider**
 
 {{#if MULTIPLE_REMOTES}}
-Since this repository has multiple git remotes, GitHub Issues is suggested as the default since it integrates with your existing GitHub workflow. However, you can choose Linear if that's your team's issue tracker.
+Since this repository has multiple git remotes, GitHub Issues is suggested as the default since it integrates with your existing GitHub workflow. However, you can choose Linear or Jira if that's your team's issue tracker.
 {{/if}}
 
 1. **Issue Tracker Provider**
@@ -881,8 +1093,9 @@ Since this repository has multiple git remotes, GitHub Issues is suggested as th
    - Options:
      - "github" - GitHub Issues (default)
      - "linear" - Linear Issues
+     - "jira" - Jira Cloud
    - Default: currentIssueProvider or "github"
-   - Validation: Must be one of: github, linear
+   - Validation: Must be one of: github, linear, jira
    - Store answer as: `issueManagement.provider`
 
 **Note on Provider + Merge Mode Combinations:**
@@ -890,6 +1103,8 @@ Since this repository has multiple git remotes, GitHub Issues is suggested as th
 - GitHub Issues + github-pr or github-draft-pr: Requires authorized GitHub CLI (`gh`)
 - Linear Issues + local merge: Requires Linear API token only
 - Linear Issues + github-pr or github-draft-pr: Requires BOTH Linear API token AND authorized GitHub CLI (`gh`)
+- Jira Cloud + local merge: Requires Jira credentials (host, username, API token) only
+- Jira Cloud + github-pr or github-draft-pr: Requires BOTH Jira credentials AND authorized GitHub CLI (`gh`)
 
 **Step 2: Provider-Specific Configuration**
 
@@ -945,6 +1160,59 @@ This repository has multiple git remotes detected. iloom needs to know which rem
    - **CRITICAL SECURITY REQUIREMENT:** This value MUST ALWAYS be saved to `settings.local.json`, NEVER to `settings.json`, regardless of which file the user selected for other settings. This token must never be committed to source control.
    - Context: Get your API token from Linear Settings → API → Personal API Keys (https://linear.app/settings/api)
 
+**If Jira was selected:**
+
+2. **Jira Host URL** (only ask if issue provider is "jira")
+   - Question format: "What is your Jira instance URL?{{#if currentJiraHost}} (Currently: [currentJiraHost]){{/if}}"
+   - Options (as examples):
+     - "https://yourcompany.atlassian.net" - Jira Cloud instance
+   - Default: currentJiraHost or NO DEFAULT (required if Jira is selected)
+   - Validation: Non-empty string, must be a valid URL. If the user provides a value without `https://`, automatically prepend `https://` (e.g., `yourcompany.atlassian.net` becomes `https://yourcompany.atlassian.net`). Strip any trailing slashes.
+   - Store answer as: `issueManagement.jira.host`
+   - Context: This is your Jira Cloud instance URL (e.g., "https://yourcompany.atlassian.net")
+
+3. **Jira Username/Email** (only ask if issue provider is "jira")
+   - Question format: "What is your Atlassian account email?{{#if currentJiraUsername}} (Currently: [currentJiraUsername]){{/if}}"
+   - Default: currentJiraUsername or NO DEFAULT (required if Jira is selected)
+   - Validation: Non-empty string
+   - Store answer as: `issueManagement.jira.username`
+   - **CRITICAL SECURITY REQUIREMENT:** This value MUST ALWAYS be saved to `settings.local.json`, NEVER to `settings.json`, regardless of which file the user selected for other settings. This is personal account information that should not be committed to source control.
+   - Context: This is the email address associated with your Atlassian account
+
+4. **Jira API Token** (only ask if issue provider is "jira")
+   - Question format: "What is your Jira API token? (Currently: 'set' or 'unset' - do not print)"
+   - Options:
+     - I have it now - use the "Type something" option to enter it
+     - I'll come back to it
+   - Default: currentJiraApiToken or NO DEFAULT
+   - Validation: Non-empty string
+   - Guidance: Choose "Type something" to enter it
+   - Store answer as: `issueManagement.jira.apiToken`
+   - **CRITICAL SECURITY REQUIREMENT:** This value MUST ALWAYS be saved to `settings.local.json`, NEVER to `settings.json`, regardless of which file the user selected for other settings. This token must never be committed to source control.
+   - Context: Generate an API token at https://id.atlassian.com/manage-profile/security/api-tokens
+
+5. **Jira Project Key** (only ask if issue provider is "jira")
+   - Question format: "What is your Jira project key?{{#if currentJiraProjectKey}} (Currently: [currentJiraProjectKey]){{/if}}"
+   - Options (as examples):
+     - "PROJ" - Project team
+     - "ENG" - Engineering team
+   - Default: currentJiraProjectKey or NO DEFAULT (required if Jira is selected)
+   - Validation: Non-empty string, typically uppercase letters
+   - Store answer as: `issueManagement.jira.projectKey`
+   - Context: This is the project key prefix shown in your Jira issue IDs (e.g., "PROJ" in "PROJ-123")
+
+6. **Jira Board ID** (only ask if issue provider is "jira")
+   - Question format: "What is your Jira board ID? (optional, used for sprint filtering){{#if currentJiraBoardId}} (Currently: [currentJiraBoardId]){{/if}}"
+   - Options:
+     - Skip - Don't configure board ID now
+     - Enter board ID - use the "Type something" option to enter it
+   - Default: currentJiraBoardId or SKIP (optional)
+   - Validation: If provided, must be a numeric string
+   - Store answer as: `issueManagement.jira.boardId`
+   - Context: The board ID can be found in the URL when viewing a Jira board (e.g., `/board/42`). This is optional and used for sprint-based filtering with `il issues --sprint`.
+
+   **Note:** Advanced Jira settings like `transitionMappings`, `doneStatuses`, `defaultIssueType`, and `defaultSubtaskType` can be configured later by editing the settings files directly. Mention this to the user.
+
 **Step 3: IDE Selection**
 
 4. **IDE Selection**
@@ -982,7 +1250,7 @@ This repository has multiple git remotes detected. iloom needs to know which rem
 
 **Implementation Details:**
 - Ask Step 1 first to determine provider
-- Then ask Step 2 based on the provider selected (includes Linear API Token if Linear was selected)
+- Then ask Step 2 based on the provider selected (includes Linear API Token if Linear was selected, or Jira credentials if Jira was selected)
 - Ask Step 3 (IDE) for all users
 - Ask Step 4 (Merge Mode) only if multiple remotes detected OR user requests advanced config
 - Set multiSelect: false for all questions
@@ -1022,9 +1290,32 @@ Based on the users answer:
 
 **Note:** Terminal colors default to `true` (always recommend unless user explicitly disables).
 
+### Phase 2.7: Swarm Quality Preference
+
+After tooling configuration (and color sync if applicable), ask the user how they want swarms to behave:
+
+```
+Swarms are iloom's most powerful feature. Give them an epic and they'll decompose it into issues, spin up parallel AI agents — each in its own isolated workspace — and build the entire thing for you. They can ship whole features, modules, or even full products.
+
+You can tune how swarms balance thinking depth versus speed:
+
+  🧠 Maximum Quality — Agents take more time to reason deeply, produce thorough analysis, and write more carefully considered code. Best when correctness matters most. Uses Opus for all agents, which is significantly more expensive.
+  ⚖️  Balanced (recommended) — Strong reasoning at a practical pace. The sweet spot for most work.
+  ⚡ Fast & Cheap — Agents move quickly through issues with lighter analysis. Great for rapid prototyping or if you're on a budget.
+```
+
+Ask: "Which swarm mode would you prefer?"
+
+- If the user picks **Maximum Quality**: apply the Maximum Quality rules (see Swarm Quality Mode in Phase 9 advanced config, item 2)
+- If the user picks **Balanced**: this is the default — no settings changes needed unless the user wants to be explicit
+- If the user picks **Fast & Cheap**: apply the Fast & Cheap rules
+- If the user says they don't use swarms or want to skip: move on without changes
+
+Include the user's choice in the Phase 3 summary under a "Swarm Mode" line.
+
 ### Phase 3: Configuration Summary
 
-After gathering all answers from Phase 1 and Phase 2, display a summary like this:
+After gathering all answers from Phase 1, Phase 2, and Phase 2.7, display a summary like this:
 
 ```
 Configuration Summary:
@@ -1040,13 +1331,19 @@ Tooling Configuration (Phase 2):
   Linear Team ID: [value] (only if issue tracker is Linear)
   Linear API Token: [configured/not configured] (only if issue tracker is Linear - never show actual token)
   {{#if MULTIPLE_REMOTES}}GitHub Remote: [value] (only if issue tracker is GitHub){{/if}}
+  Jira Host: [value] (only if issue tracker is Jira)
+  Jira Project Key: [value] (only if issue tracker is Jira)
+  Jira Board ID: [value or "not configured"] (only if issue tracker is Jira)
+  Jira API Token: [configured/not configured] (only if issue tracker is Jira - never show actual token)
   IDE: [value or "vscode (default)"]
   Merge Mode: [value] (only if configured)
+  Swarm Mode: [Maximum Quality / Balanced / Fast & Cheap] (only if configured in Phase 2.7)
 ```
 
 **Note**:
 - Include the GitHub Remote line in the summary ONLY if it was configured in Phase 2 (multiple remotes and GitHub selected)
 - Include Linear Team ID ONLY if Linear was selected as the issue tracker provider
+- Include Jira Host, Project Key, Board ID, and API Token ONLY if Jira was selected as the issue tracker provider
 - Include Merge Mode ONLY if it was asked and configured (multiple remotes or advanced config)
 
 Then ask: "Does this configuration look correct?"
@@ -1185,6 +1482,46 @@ When both settings.json and settings.local.json exist, you MUST prevent duplicat
    }
    ```
 
+   **For Jira:**
+
+   In settings.json (committed):
+   ```json
+   {
+     "issueManagement": {
+       "provider": "jira",
+       "jira": {
+         "host": "<user's Jira host URL>",
+         "projectKey": "<user's project key>"
+       }
+     }
+   }
+   ```
+
+   In settings.local.json (gitignored - MUST be separate from settings.json):
+   ```json
+   {
+     "issueManagement": {
+       "jira": {
+         "username": "<user's Atlassian email>",
+         "apiToken": "<user's API token>"
+       }
+     }
+   }
+   ```
+
+   If a boardId was provided, add it to settings.json alongside host and projectKey:
+   ```json
+   {
+     "issueManagement": {
+       "jira": {
+         "boardId": "<user's board ID>"
+       }
+     }
+   }
+   ```
+
+   **CRITICAL:** The `username` and `apiToken` fields MUST be saved to `settings.local.json`, never to `settings.json`. The `host`, `projectKey`, and `boardId` fields are safe to commit in `settings.json`.
+
 6. **Add mergeBehavior ONLY if mode is not "local":**
    ```json
    {
@@ -1315,16 +1652,16 @@ Would you like to commit these changes?
   - Yes - Commit iloom configuration changes (strongly recommended)
   - No - Skip committing (not recommended)
 
-⚠️  WARNING: If you don't commit settings.json, iloom will not work correctly in new looms.
+⚠️  WARNING: If you don't commit settings.json and package.iloom.json, iloom will not work correctly in new looms.
     Looms are created from committed code, so your configuration won't be available.
-    (Local files like settings.local.json and .env are copied automatically - but settings.json must be committed.)
+    (Local files like settings.local.json, package.iloom.local.json, and .env are copied automatically - but shared files must be committed.)
 ```
 
 **CRITICAL RULES:**
-- **ONLY commit iloom-related files**: .iloom/settings.json, .gitignore
+- **ONLY commit iloom-related files**: .iloom/settings.json, .iloom/package.iloom.json, .gitignore
 - **NEVER stage or commit unrelated files** - even if they appear in `git status`
 - **If the commit fails, you must then subsequently request to use --no-verify flag** to bypass pre-commit hooks that might fail due to unrelated codebase state
-- **Do NOT commit settings.local.json** - it should be gitignored, not committed
+- **Do NOT commit local-only files** - settings.local.json and package.iloom.local.json should be gitignored, not committed
 - **YOU MAY NEED TO EDIT/UPDATE MORE THAN ONE FILE if the user is changing something like API Keys (local only), permissionsMode (local only), IDE (recommened global) as well as shared settings.
 
 **Step 3: If user says yes, commit the changes**
@@ -1333,10 +1670,10 @@ VERIFY YOU'RE NOT BUNDLING ALL CHANGES IN ONE FILE DESPITE GUIDANCE TO SPLIT ACC
 
 Stage ONLY the iloom-related files that should be committed:
 ```bash
-git add .iloom/settings.json .gitignore 2>/dev/null || true
+git add .iloom/settings.json .iloom/package.iloom.json .gitignore 2>/dev/null || true
 ```
 
-Note: Do NOT add .iloom/settings.local.json - it's meant to be local-only.
+Note: Do NOT add local-only files (.iloom/settings.local.json, .iloom/package.iloom.local.json) - they should be gitignored, not committed.
 
 Then commit:
 
@@ -1404,6 +1741,8 @@ Need more advanced configuration? I can help you set up:
   • Multi-Provider Code Review - Get code reviews from Gemini or Codex alongside Claude
   • Plan Configuration - Use different AI providers for planning and plan review
   • Agent Models - Use different Claude models for different tasks
+  • Swarm Agent Models - Configure different models for agents when running in swarm mode
+  • Swarm Quality Mode - Control how deeply swarm agents reason vs how fast they move (also offered during initial setup)
   • Database Settings - Configure database branching for isolated development
   • Skip Pre-Commit Hooks - Bypass slow or failing hooks during commit and finish workflows
   • Workflow Behavior - Control permissions, IDE launching, dev servers, and terminal behavior
@@ -1421,6 +1760,9 @@ You can ask me questions like:
   "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?"
+  "How do I use different models for swarm workers vs normal mode?"
+  "How do I change the swarm quality mode?"
+  "What's the difference between maximum quality and fast & cheap swarms?"
   "How do I use custom build/test commands instead of package.json scripts?"
 
 Just ask any of these questions and I'll help you modify your settings.
@@ -1452,7 +1794,50 @@ When configuring agents, use these model identifiers:
    }
    ```
 
-2. **Database Environment Variable:**
+   **Important: Non-swarm and swarm models are independent.** Changing an agent's `model` here only affects non-swarm mode (single-issue looms via `il start`). Swarm mode has its own model configuration via `swarmModel` and the Swarm Quality Mode presets (see item 2 below). This separation is intentional — swarms run many agents in parallel and costs scale quickly, so swarm models should be an explicit choice.
+
+   **Swarm-Specific Phase Agent Models:**
+
+   To override a specific agent's model in swarm mode, use `swarmModel`:
+
+   ```json
+   "agents": {
+     "iloom-issue-implementer": {
+       "model": "opus",
+       "swarmModel": "sonnet"
+     }
+   }
+   ```
+
+   In this example, the implementer uses Opus in non-swarm mode but Sonnet in swarm mode. If no `swarmModel` is set, the Swarm Quality Mode defaults apply (see item 2 below) — not the agent's base `model`.
+
+2. **Swarm Quality Mode:**
+
+   This controls the trade-off between reasoning quality and speed/cost for swarm agents. The same choice is offered proactively in Phase 2.7. Users can also change it here after initial setup.
+
+   | Mode | Focus | Models used | Best for |
+   |------|-------|-------------|----------|
+   | **Maximum Quality** | Deepest reasoning, best analysis | Opus everywhere (except complexity evaluator stays Haiku) | Complex epics, critical features |
+   | **Balanced** (default) | Opus for analysis, Sonnet for everything else | Opus: analyzer, analyze-and-plan. Sonnet: orchestrator, worker, planner, implementer, enhancer, code-reviewer. Haiku: complexity evaluator | Most tasks |
+   | **Fast & Cheap** | Quick iterations, lowest cost | Haiku everywhere | Simple tasks, rapid prototyping |
+
+   Note: The complexity evaluator always stays on Haiku regardless of mode, since it performs a simple classification task that does not benefit from a larger model.
+
+   **Rules for generating settings JSON:**
+
+   When the user selects a mode, **merge** the model values into their existing settings. Only set the `swarmModel` (or `model` for the worker) field on each agent — do not overwrite or remove other agent settings.
+
+   - **Maximum Quality:** Set `spin.swarmModel` to `"opus"`. Set `agents.iloom-swarm-worker.model` to `"opus"`. Set `swarmModel` to `"opus"` on all phase agents (`iloom-issue-analyzer`, `iloom-issue-planner`, `iloom-issue-implementer`, `iloom-issue-enhancer`, `iloom-issue-analyze-and-plan`, `iloom-code-reviewer`). Keep `iloom-issue-complexity-evaluator.swarmModel` as `"haiku"`.
+   - **Balanced (default):** Set `spin.swarmModel` to `"sonnet"`. Set `agents.iloom-swarm-worker.model` to `"sonnet"`. Set `swarmModel` to `"opus"` on analysis agents (`iloom-issue-analyzer`, `iloom-issue-analyze-and-plan`). Set `swarmModel` to `"sonnet"` on all other phase agents (`iloom-issue-planner`, `iloom-issue-implementer`, `iloom-issue-enhancer`, `iloom-code-reviewer`). Keep `iloom-issue-complexity-evaluator.swarmModel` as `"haiku"`.
+   - **Fast & Cheap:** Set `spin.swarmModel` to `"haiku"`. Set `agents.iloom-swarm-worker.model` to `"haiku"`. Set `swarmModel` to `"haiku"` on all phase agents and `iloom-issue-complexity-evaluator`.
+
+   **Important notes:**
+   - These set `swarmModel` on phase agents (not `model`), so non-swarm behavior is preserved. When agents run outside of swarm mode, their base `model` setting is used.
+   - Only merge into existing agent settings — never replace the entire agent object.
+   - If the user has already configured per-agent models, the mode values take precedence for swarm-related model fields only.
+   - If the user is unsure, recommend **Balanced**.
+
+3. **Database Environment Variable:**
    ```json
    "capabilities": {
      "database": {
@@ -1461,7 +1846,7 @@ When configuring agents, use these model identifiers:
    }
    ```
 
-3. **Workflow Behavior:**
+4. **Workflow Behavior:**
    ```json
    "workflows": {
      "pr": {
@@ -1473,26 +1858,26 @@ When configuring agents, use these model identifiers:
    }
    ```
 
-4. **Copy Gitignored Files:**
+5. **Copy Gitignored Files:**
    ```json
    "copyGitIgnoredPatterns": ["*.db", "data/*.sqlite", "tmp/fixtures/**"]
    ```
 
    Glob patterns for gitignored files that should be copied to new looms. Useful for local databases, large test fixtures, or generated files that are too big to commit. Note: `.env` files and iloom/claude local settings are automatically copied and don't need to be listed here.
 
-5. **Protected Branches:**
+6. **Protected Branches:**
    ```json
    "protectedBranches": ["main", "production", "release/*"]
    ```
 
-6. **IDE Configuration:**
+7. **IDE Configuration:**
    ```json
    "ide": {
      "type": "cursor"
    }
    ```
 
-7. **Code Review with Multiple Providers:**
+8. **Code Review with Multiple Providers:**
    ```json
    "agents": {
      "iloom-code-reviewer": {
@@ -1506,7 +1891,7 @@ When configuring agents, use these model identifiers:
 
    This configures the code reviewer to use both Claude and Gemini for reviews. Multiple providers can be configured to get reviews from different AI models.
 
-8. **Custom Script Configuration (package.iloom.json):**
+9. **Custom Script Configuration (package.iloom.json):**
 
    If users want to override or supplement npm scripts with custom commands, help them create `.iloom/package.iloom.json`:
    ```json
@@ -1564,6 +1949,15 @@ When configuring agents, use these model identifiers:
    - Your local environment needs different commands than the team standard
    - You want to add debug flags or local-only tooling without affecting others
 
+## Telemetry
+
+iloom collects anonymous usage data to improve the product. If the user asks about telemetry or data collection during setup:
+
+- **CLI telemetry**: Managed via `il telemetry off` (disable) and `il telemetry on` (re-enable). Run `il telemetry status` to check current state.
+- **VS Code extension telemetry**: If the user also uses the iloom VS Code extension, its telemetry is managed separately via VS Code settings (`iloom.telemetry.enabled`). Disabling CLI telemetry does NOT affect the extension, and vice versa.
+- **What's collected**: Only anonymous usage events (commands run, errors). No personal information, repo names, or code.
+- **Distinct ID**: A random UUID stored in `~/.config/iloom-ai/telemetry.json`, shared between CLI and VS Code extension.
+
 ## Important Notes
 
 - **Validate ALL inputs** against the schema before writing files
@@ -1581,3 +1975,5 @@ When configuring agents, use these model identifiers:
 - **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)
+- **ALWAYS ask where to save package.iloom configuration** - When creating or modifying package.iloom.json outside of the guided wizard flow, always ask the user whether to save to `package.iloom.json` (shared, committed) or `package.iloom.local.json` (local, gitignored) before writing. Apply the same fork detection logic — if origin + upstream remotes are detected, default to the local variant.
+- **ALWAYS offer to commit after writing shared files** - Whenever you create or modify a committable file (settings.json, package.iloom.json, .gitignore), offer to commit it — even outside the guided wizard flow. Looms are created from committed code, so uncommitted shared configuration won't be available in new looms. Follow the same commit rules from Phase 7: only stage iloom-related files, never stage local-only files.