bmad-stella 1.0.0 → 1.0.1

package/README.md

@@ -52,8 +52,9 @@ npx bmad-stella install
 3. Enter Confluence URL for architecture docs
 4. Select **Claude Code** as IDE
 5. Skip web bundles installation (enter `n`)
-6. Configure Atlassian MCP Server (enter `y`)
-7. Provide JIRA instance URL (e.g., `https://stellaint.atlassian.net`)
+6. Allow Claude Code Permissions Setup (enter `y`)
+7. Configure Atlassian MCP Server (enter `y`)
+8. Provide JIRA instance URL (e.g., `https://stellaint.atlassian.net`)
 
 **📖 [Detailed Installation Guide](docs/stella-user-guide.md#bmad-stella-installation-process)**
 

package/bmad-core/agents/dev.md

@@ -58,12 +58,14 @@ core_principles:
 
 # All commands require * prefix when used (e.g., *help)
 commands:
-  - help: Show numbered list of the following commands to allow selection
+  - help: Show numbered list of the following commands to allow selection. Format each as "{number}. *{command-name} {parameters} - {description}"
   - implement-task:
-      - order-of-execution: 'Read (first or next) task from implementation plan→Implement Task and its subtasks→Write tests→Execute validations→Only if ALL pass, then update the task checkbox with [x] in plan→Update plan section File List to ensure it lists any new or modified or deleted source file→HALT and ask user if they want to proceed to next task→If yes, repeat order-of-execution; if no, remain HALTED'
+      - order-of-execution: 'Read (first or next) task from implementation plan→Implement Task and its subtasks→Update the task checkbox with [x] in plan→Update plan file `File List` subsection in `Dev Agent Record` section to ensure it lists any new or modified or deleted source file→HALT and ask user: "Proceed to next task, build project, or stop?"→If next task: repeat order-of-execution→If build: run build command and report result then ask "Proceed to next task or stop?"→If stop: remain HALTED'
       - plan-file-updates-ONLY:
           - CRITICAL: ONLY UPDATE THE IMPLEMENTATION PLAN FILE WITH UPDATES TO SECTIONS INDICATED BELOW. DO NOT MODIFY ANY OTHER SECTIONS.
-          - CRITICAL: You are ONLY authorized to edit these specific sections of implementation plan files - Tasks / Subtasks Checkboxes, Dev Agent Record section (Agent Model Used, Debug Log References, Completion Notes List, File List), Change Log, Status
+          - CRITICAL: Don't ask for user permission for plan file update.
+          - CRITICAL: MUST UPDATE `Agent Model Used` and `File List` SUBSECTION IN `Dev Agent Record` SECTION OF IMPLEMENTATION PLAN
+          - CRITICAL: You are ONLY authorized to edit these specific sections of implementation plan files - Tasks / Subtasks Checkboxes, `Dev Agent Record` section (Agent Model Used, Debug Log References, Completion Notes List, File List), Change Log, Status
           - CRITICAL: DO NOT modify Ticket Information, Requirements, Acceptance Criteria, Technical Approach, Technical Context / Dev Notes, Files to Change, Dependencies and Risks, Feedback, or any other sections not listed above
       - interaction-rules:
           - Don't perform DB Migrations and manual tests automatically. Ask user to perform these and wait for confirmation before going to the next step
@@ -74,8 +76,8 @@ commands:
       - ready-for-review: 'Code matches requirements + All validations pass + Follows standards + File List complete in Dev Agent Record'
       - completion: "All Tasks and Subtasks marked [x] and have tests→Validations and full regression passes (DON'T BE LAZY, EXECUTE ALL TESTS and CONFIRM)→Ensure Dev Agent Record File List is Complete→run the task execute-checklist for the checklist task-dod-checklist→set plan status: 'Ready for Review'→HALT"
   - explain: teach me what and why you did whatever you just did in detail so I can learn. Explain to me as if you were training a junior engineer.
-  - comment-plan {plan-file}: Post implementation summary to Jira ticket using Atlassian MCP server using Jira markdown formatting
-      - order-of-execution: Extract Jira ticket number/URL from plan file Ticket Information section→Verify Atlassian MCP server connectivity→Check if Acceptance Criteria already exists in Jira ticket description→Format comment according to comment-structure   rules→Display formatted comment to user and request permission to post→Post comment to Jira ticket→Display Jira ticket URL and confirm successful posting
+  - comment-plan {plan-file}:
+      - order-of-execution: 'Extract Jira ticket number/URL from plan file Ticket Information section→Attempt to fetch Jira ticket using atlassian MCP→If fetch fails, notify user: "Atlassian MCP not connected. Please reauthenticate."→If connected, check if Acceptance Criteria already exists in Jira ticket description→Format comment according to comment-structure rules using Jira markdown formatting→Display formatted comment to user and request permission to post→Post comment to Jira ticket→Display Jira ticket URL and confirm successful posting'
       - comment-structure:
            - Section 1 - Tasks Completed: Copy all tasks and subtasks from Tasks/Subtasks section exactly as written with their checkbox status ([x] or [ ])
           - Section 2 - Technical Summary: Write a 5-10 sentence summary describing what was implemented based on Technical Approach section content

package/bmad-core/agents/planner.md

@@ -20,7 +20,7 @@ activation-instructions:
   - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
   - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
   - STEP 3: Load and read `.bmad-core/core-config.yaml` (project configuration) before any greeting
-  - STEP 4: Read documentation from the `architectureFolderUrl` in `.bmad-core/core-config.yaml`. Delete and recreate the `architecture/` folder inside `bmad-docs/` if it exists. Save content into files named coding-standards, tech-stack, git-workflow, and project-structure based on content meaning rather than page names, and save any additional pages as separate files if present. Number of files should be same as number of child pages in provided url. If atlassian mcp shows authentication/login required, inform user to authenticate Atlassian MCP, HALT activation process, wait for user confirmation of authentication, then retry STEP 4. Do NOT proceed to STEP 5 until architecture docs are successfully loaded.
+  - STEP 4: Before any greeting, fetch documentation from the `architectureFolderUrl` in `.bmad-core/core-config.yaml`. Delete and recreate the `architecture/` folder inside `bmad-docs/` if it exists. Use "Bash(rm -rf **/bmad-docs/architecture)" OR "Bash(rm -rf bmad-docs/architecture)" to delete architecture folder. Save content into files named coding-standards, tech-stack, git-workflow, and project-structure based on content meaning rather than page names, and save any additional pages as separate files if present. Number of files should be same as number of child pages in provided url. If attempt to fetch pages fail using atlassian MCP, notify user - "Atlassian MCP not connected. Please reauthenticate.", then retry STEP 4. Do NOT proceed to STEP 5 until architecture docs are successfully loaded.
   - STEP 5: Greet user with your name/role and immediately run `*help` to display available commands
   - DO NOT: Load any other agent files during activation
   - ONLY load dependency files when user selects them for execution via command or request of a task
@@ -60,10 +60,10 @@ persona:
     - Standards & Patterns Adherence - Ensure plans align with project conventions
 # All commands require * prefix when used (e.g., *help)
 commands:
-  - help: Show numbered list of the following commands to allow selection
-  - retrieve-ticket-information {ticket-number-or-url}: Retrieve and validate JIRA ticket information using Atlassian MCP server, preparing it for implementation planning
-      - order-of-execution: Verify Atlassian MCP server connectivity→Fetch ticket information (title, description, comments, attachments) using ticket number/URL→Check for Requirements or Acceptance Criteria in ticket description→If absent, check for attached images and request user to provide them via copy/paste (alt+v) or file path if downloaded→Prepare Acceptance Criteria text based on ticket description, comments, and provided attachments→Display ticket contents with prepared Acceptance Criteria and request user validation→Prompt user to proceed with draft-plan command. If no ticket identifier provided, ask for one
-      - attachment-rules: if there exists any attachments in the ticket request user to provide them via copy/paste (alt+v) or file path if downloaded
+  - help: Show numbered list of the following commands to allow selection. Format each as "{number}. *{command-name} {parameters} - {description}"
+  - retrieve-ticket-information {ticket-number-or-url}:
+      - order-of-execution: 'Fetch ticket information (title, description, comments, attachments) using ticket number/URL with `atlassian` MCP→If fetch fails, notify user: "Atlassian MCP not connected. Please reauthenticate." and HALT until user confirms reconnection, then retry fetch→Check for Requirements or Acceptance Criteria in ticket description→If absent, check for attached images and request user to provide them via copy/paste (alt+v) or file path if downloaded→Prepare Acceptance Criteria text based on ticket description, comments, and provided attachments→Display ticket contents with prepared Acceptance Criteria and request user validation→Prompt user to proceed with draft-plan command. If no ticket identifier provided, ask for one'
+      - attachment-rules: If there exists any attachments in the ticket request user to provide them via copy/paste (alt+v) or file path if downloaded
       - acceptance-criteria-rules: Prepare criteria only if Requirements AND Acceptance Criteria sections are both absent. Request attachments first if present. Format as testable, numbered list based on ticket description and attachments. Do not create any files - only compose text for display
       - output-format: Display ticket title, description, comments, attachments list, and prepared Acceptance Criteria (if created) with clear validation prompt
   - draft-plan {ticket-file-or-description}: Analyze JIRA ticket (feature/bug/migration) information with description having `Acceptance Criteria`/ `Requirements` and create detailed implementation plan with step-by-step tasks executing create-implementation-plan

package/bmad-core/agents/qa.md

@@ -62,7 +62,7 @@ task-file-permissions:
   - Assessment documents include: test-design-*.md, trace-*.md files
 # All commands require * prefix when used (e.g., *help)
 commands:
-  - help: Show numbered list of the following commands to allow selection
+  - help: Show numbered list of the following commands to allow selection. Format each as "{number}. *{command-name} {parameters} - {description}"
   - test-design {task-file}: Execute test-design task to create comprehensive test scenarios
   - implement-test {task-file}: Execute implement-test task to write test code from test design scenarios
   - trace {task-file}: Execute trace-requirements task to map requirements to tests using Given-When-Then

package/bmad-core/tasks/create-implementation-plan.md

@@ -16,6 +16,7 @@ To transform JIRA tickets (features, bugs, migrations) into comprehensive, actio
    - **Get search hints first:** Ask user for helpful hints to narrow the search (e.g., "Look in services folder", "Related to authentication", "Files with 'payment' in name", "Backend API files")
    - **Check project structure docs:** ALWAYS read `bmad-docs/architecture/project-structure.md` (or `project-structure.md`) FIRST to understand file locations and naming conventions
    - **Perform targeted search:** Use hints + structure knowledge to create focused Glob/Grep searches instead of broad codebase scans
+   - **Identify impacted files:** When modifying a function, component, or interface, search for its usages across codebase using targeted Glob/Grep before making changes. Update all impacted files accordingly.
 
 ## SEQUENTIAL Task Execution (Do not proceed until current Task is complete)
 
@@ -84,14 +85,14 @@ If critical information is missing, ask the user targeted questions:
 
 **For Database Changes (All Ticket Types):**
 
-- Does this work require any database table updates or creation?
-- **If uncertain, ASK the user** - better to clarify than assume
+- Analyze Does this work require any database table updates or creation?
+- **If not mentioned in ticket and uncertain, ASK the user** - better to clarify than assume
 - If YES:
   - **Database migration tasks must be handled by the user** (add in tasks list but tell user to do this)
   - If specific fields to add to a model or a new model structure are NOT specified in the ticket info/requirements:
     - **Ask the user to specify the fields to be added or the model structure** (field names, types, constraints, relationships)
   - **If uncertain about any database-related details, ALWAYS ask the user** - do not make assumptions or proceed silently
-  - Document the model/table changes needed in the Technical Approach sectio
+  - Document the model/table changes needed in the Technical Approach section
 
 **CRITICAL:** Only ask essential questions. Use your senior developer judgment to infer reasonable details when possible.
 

package/docs/stella-user-guide.md

@@ -28,7 +28,7 @@ Before installing BMad-Stella, ensure you have:
 Open your terminal and run:
 
 ```bash
-npx github:Asrarul-BS23/BMad-Stella install
+npx bmad-stella install
 ```
 
 #### Step 2: Provide Project Directory
@@ -87,7 +87,17 @@ When prompted about web bundles:
 
 Enter: **n**
 
-#### Step 7: Configure Atlassian MCP Server
+#### Step 7: Allow Claude Code Permissions Setup
+
+When prompted about permission setup:
+
+```
+Add 32 missing BMAD permissions to existing settings.local.json? (Y/n)
+```
+
+Enter: **y**
+
+#### Step 8: Configure Atlassian MCP Server
 
 If Atlassian MCP is not already configured, you'll see:
 
@@ -110,7 +120,7 @@ Enter: `https://stellaint.atlassian.net` (or your organization's JIRA URL)
 - MCP server configuration is created
 - Authentication is required to connect with JIRA instance
 
-#### Step 8: Complete Installation
+#### Step 9: Complete Installation
 
 You should see:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-stella",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Breakthrough Method of Agile AI-driven Development (Customized for Stella)",
   "keywords": [
     "agile",

package/tools/installer/lib/claude-permissions-manager.js

@@ -0,0 +1,380 @@
+const fs = require('fs-extra');
+const path = require('node:path');
+const chalk = require('chalk').default || require('chalk');
+const inquirer = require('inquirer').default || require('inquirer');
+const cjson = require('comment-json');
+
+class ClaudePermissionsManager {
+  constructor() {
+    // Define BMAD required permissions for Claude Code
+    this.bmadPermissions = [
+      // Atlassian MCP tools
+      'mcp__atlassian__getConfluencePage',
+      'mcp__atlassian__getConfluencePageDescendants',
+      'mcp__atlassian__getJiraIssue',
+      'mcp__atlassian__searchJiraIssuesUsingJql',
+      'mcp__atlassian__fetch',
+      'mcp__atlassian__addCommentToJiraIssue',
+
+      'WebFetch(domain:stellaint.atlassian.net)',
+
+      // File operations for markdown files
+      'Write(bmad-docs/**)',
+      'Write(*bmad-docs*)',
+      'Edit(bmad-docs/**)',
+      'Edit(*bmad-docs*)',
+
+      // Bash commands for directory operations (Unix)
+      'Bash(mkdir -p bmad-docs/**)',
+      'Bash(mkdir -p **/bmad-docs/**)',
+      'Bash(mkdir bmad-docs/**)',
+      'Bash(mkdir **/bmad-docs/**)',
+      'Bash(rm -rf *bmad-docs*)',
+      'Bash(rm -rf */bmad-docs/architecture*)',
+      'Bash(rm *bmad-docs*)',
+      'Bash(rm */bmad-docs/architecture*)',
+      'Bash(rm bmad-docs/temporary/*.md)',
+      'Bash(rm **/bmad-docs/temporary/*.md)',
+
+      // Bash commands for directory operations (Windows)
+      'Bash(if exist *bmad-docs* rmdir /s /q *bmad-docs*)',
+      String.raw`Bash(if exist *bmad-docs\architecture* rmdir /s /q *bmad-docs\architecture*)`,
+      'Bash(mkdir *bmad-docs*)',
+
+      // Directory listing and existence checks (Unix)
+      'Bash(ls bmad-docs/**)',
+      'Bash(ls **/bmad-docs/**)',
+      'Bash(test -f bmad-docs/**)',
+      'Bash(test -f **/bmad-docs/**)',
+      'Bash(test -d bmad-docs/**)',
+      'Bash(test -d **/bmad-docs/**)',
+      'Bash([ -f bmad-docs/** ])',
+      'Bash([ -d bmad-docs/** ])',
+
+      // Directory listing (Windows)
+      'Bash(dir bmad-docs/**)',
+      'Bash(dir **/bmad-docs/**)',
+      'Bash(dir *bmad-docs*)',
+    ];
+  }
+
+  /**
+   * Get the path to settings.local.json
+   * @param {string} installDir - Target installation directory
+   * @returns {string} Path to settings.local.json
+   */
+  getSettingsPath(installDir) {
+    return path.join(installDir, '.claude', 'settings.local.json');
+  }
+
+  /**
+   * Check if settings.local.json exists
+   * @param {string} installDir - Target installation directory
+   * @returns {Promise<boolean>}
+   */
+  async settingsExists(installDir) {
+    const settingsPath = this.getSettingsPath(installDir);
+    return fs.pathExists(settingsPath);
+  }
+
+  /**
+   * Read existing settings.local.json
+   * @param {string} installDir - Target installation directory
+   * @returns {Promise<object|null>} Parsed settings or null if not found
+   */
+  async readSettings(installDir) {
+    const settingsPath = this.getSettingsPath(installDir);
+
+    try {
+      if (!(await fs.pathExists(settingsPath))) {
+        return null;
+      }
+
+      const content = await fs.readFile(settingsPath, 'utf8');
+
+      try {
+        // Try parsing with comment-json to preserve comments
+        return cjson.parse(content);
+      } catch {
+        // Fallback to standard JSON
+        return JSON.parse(content);
+      }
+    } catch (error) {
+      console.warn(chalk.yellow(`Warning: Could not read settings.local.json: ${error.message}`));
+      return null;
+    }
+  }
+
+  /**
+   * Write settings.local.json
+   * @param {string} installDir - Target installation directory
+   * @param {object} settings - Settings object to write
+   * @returns {Promise<boolean>}
+   */
+  async writeSettings(installDir, settings) {
+    const claudeDir = path.join(installDir, '.claude');
+    const settingsPath = this.getSettingsPath(installDir);
+
+    try {
+      // Ensure .claude directory exists
+      await fs.ensureDir(claudeDir);
+
+      // Write with pretty formatting
+      const output = cjson.stringify(settings, null, 2);
+      await fs.writeFile(settingsPath, output, 'utf8');
+      return true;
+    } catch (error) {
+      console.error(chalk.red(`Failed to write settings.local.json: ${error.message}`));
+      return false;
+    }
+  }
+
+  /**
+   * Get list of missing BMAD permissions from current settings
+   * @param {object} settings - Current settings object
+   * @returns {string[]} Array of missing permission strings
+   */
+  getMissingPermissions(settings) {
+    const existingPermissions = new Set(settings?.permissions?.allow || []);
+    return this.bmadPermissions.filter((perm) => !existingPermissions.has(perm));
+  }
+
+  /**
+   * Check and setup Claude Code permissions
+   * @param {string} installDir - Target installation directory
+   * @param {object} spinner - Ora spinner instance (optional)
+   * @returns {Promise<object>} Results object with status
+   */
+  async checkAndSetupPermissions(installDir, spinner = null) {
+    const results = {
+      settingsExisted: false,
+      created: false,
+      updated: false,
+      skipped: false,
+      permissionsAdded: 0,
+      error: null,
+    };
+
+    try {
+      const settingsPath = this.getSettingsPath(installDir);
+      results.settingsExisted = await this.settingsExists(installDir);
+
+      if (spinner) spinner.stop();
+
+      // Always show permissions setup prompt
+      console.log(chalk.cyan('\n🔧 Claude Code Permissions Setup'));
+      console.log(
+        chalk.dim('BMAD agents require certain permissions to work without repeated prompts.'),
+      );
+      console.log(
+        chalk.dim(
+          '(Only for bmad-docs/ and Atlassian MCP - does NOT include source code changes)\n',
+        ),
+      );
+
+      if (results.settingsExisted) {
+        // Settings file exists - check for missing permissions
+        const settings = await this.readSettings(installDir);
+
+        if (!settings) {
+          results.error = 'Could not parse existing settings.local.json';
+          console.log(chalk.yellow(`⚠️  ${results.error}`));
+          if (spinner) spinner.start();
+          return results;
+        }
+
+        // Ensure permissions.allow array exists
+        if (!settings.permissions) {
+          settings.permissions = {};
+        }
+        if (!settings.permissions.allow) {
+          settings.permissions.allow = [];
+        }
+
+        // Find missing permissions
+        const missingPermissions = this.getMissingPermissions(settings);
+
+        if (missingPermissions.length > 0) {
+          // Ask user before adding permissions
+          const { updateSettings } = await inquirer.prompt([
+            {
+              type: 'confirm',
+              name: 'updateSettings',
+              message: `Add ${missingPermissions.length} missing BMAD permissions to existing settings.local.json?`,
+              default: true,
+            },
+          ]);
+
+          if (!updateSettings) {
+            console.log(chalk.yellow('⚠️  Skipping Claude Code permissions update.'));
+            results.skipped = true;
+            if (spinner) spinner.start();
+            return results;
+          }
+
+          // Add missing permissions
+          settings.permissions.allow.push(...missingPermissions);
+
+          const success = await this.writeSettings(installDir, settings);
+
+          if (success) {
+            results.updated = true;
+            results.permissionsAdded = missingPermissions.length;
+            console.log(chalk.green('✓ Updated .claude/settings.local.json with BMAD permissions'));
+            console.log(chalk.dim(`  - Added ${missingPermissions.length} new permission rules`));
+          } else {
+            results.error = 'Failed to update settings file';
+          }
+        } else {
+          console.log(chalk.green('✓ BMAD permissions already present in settings.local.json'));
+        }
+      } else {
+        // Ask user if they want to create settings.local.json
+        const { createSettings } = await inquirer.prompt([
+          {
+            type: 'confirm',
+            name: 'createSettings',
+            message: 'Grant Claude Code with BMAD related permissions? (Recommended)',
+            default: true,
+          },
+        ]);
+
+        if (!createSettings) {
+          console.log(chalk.yellow('⚠️  Skipping Claude Code permissions setup.'));
+          console.log(
+            chalk.dim('   You may be prompted for permissions when using BMAD agents.\n'),
+          );
+          results.skipped = true;
+          if (spinner) spinner.start();
+          return results;
+        }
+
+        // Create new settings file
+        const settings = {
+          permissions: {
+            allow: [...this.bmadPermissions],
+          },
+        };
+
+        const success = await this.writeSettings(installDir, settings);
+
+        if (success) {
+          results.created = true;
+          results.permissionsAdded = this.bmadPermissions.length;
+          console.log(chalk.green('✓ Created .claude/settings.local.json with BMAD permissions'));
+          console.log(chalk.dim(`  - Added ${this.bmadPermissions.length} permission rules`));
+        } else {
+          results.error = 'Failed to create settings file';
+        }
+      }
+
+      if (spinner) spinner.start();
+      return results;
+    } catch (error) {
+      results.error = error.message;
+      console.log(chalk.yellow(`⚠️  Could not setup Claude Code permissions: ${error.message}`));
+      if (spinner) spinner.start();
+      return results;
+    }
+  }
+
+  /**
+   * Show summary of permissions setup
+   * @param {object} results - Results from checkAndSetupPermissions
+   */
+  showSetupSummary(results) {
+    if (results.error) {
+      console.log(chalk.red(`\n✗ Claude Code permissions setup failed: ${results.error}`));
+      console.log(chalk.yellow('You may need to add BMAD permissions manually.'));
+      this.showManualInstructions();
+      return;
+    }
+
+    if (results.skipped) {
+      console.log(chalk.yellow('\n⚠️  Claude Code permissions were not configured.'));
+      console.log(chalk.dim('   Run the installer again or add permissions manually.'));
+      return;
+    }
+
+    if (results.created) {
+      console.log(chalk.green('\n✓ Claude Code permissions configured successfully!'));
+      console.log(chalk.dim(`   ${results.permissionsAdded} permission rules added.`));
+    } else if (results.updated) {
+      console.log(chalk.green('\n✓ Claude Code permissions updated successfully!'));
+      console.log(chalk.dim(`   ${results.permissionsAdded} new permission rules added.`));
+    }
+  }
+
+  /**
+   * Show manual setup instructions
+   */
+  showManualInstructions() {
+    console.log(chalk.cyan('\n📋 Manual Setup Instructions:'));
+    console.log(chalk.dim('1. Create .claude/settings.local.json in your project root'));
+    console.log(chalk.dim('2. Add the following content:\n'));
+
+    const exampleSettings = {
+      permissions: {
+        allow: [...this.bmadPermissions.slice(0, 5), '... (see full list in docs)'],
+      },
+    };
+
+    console.log(chalk.dim(JSON.stringify(exampleSettings, null, 2)));
+    console.log(
+      chalk.dim('\nSee BMAD documentation for the complete list of required permissions.'),
+    );
+  }
+
+  /**
+   * Add custom permissions to an existing or new settings file
+   * @param {string} installDir - Target installation directory
+   * @param {string[]} customPermissions - Array of custom permission strings
+   * @returns {Promise<boolean>}
+   */
+  async addCustomPermissions(installDir, customPermissions) {
+    try {
+      let settings = await this.readSettings(installDir);
+
+      if (!settings) {
+        settings = { permissions: { allow: [] } };
+      }
+
+      if (!settings.permissions) {
+        settings.permissions = {};
+      }
+      if (!settings.permissions.allow) {
+        settings.permissions.allow = [];
+      }
+
+      const existingPermissions = new Set(settings.permissions.allow);
+      let addedCount = 0;
+
+      for (const permission of customPermissions) {
+        if (!existingPermissions.has(permission)) {
+          settings.permissions.allow.push(permission);
+          addedCount++;
+        }
+      }
+
+      if (addedCount > 0) {
+        await this.writeSettings(installDir, settings);
+        console.log(chalk.green(`✓ Added ${addedCount} custom permissions`));
+      }
+
+      return true;
+    } catch (error) {
+      console.error(chalk.red(`Failed to add custom permissions: ${error.message}`));
+      return false;
+    }
+  }
+
+  /**
+   * Get all BMAD permissions
+   * @returns {string[]} Array of all BMAD permission strings
+   */
+  getAllPermissions() {
+    return [...this.bmadPermissions];
+  }
+}
+
+module.exports = new ClaudePermissionsManager();