---
name: configure
description: Generate or update project-level plugin configuration with smart migration
version: 2.0.0
---

# Configure Plugin Settings

This command helps you set up `.claude/super-claude-config.json` for customizing plugin behavior (skills and hooks).

## What This Does

Creates or updates `.claude/super-claude-config.json` with configuration for:

- **Skills** - Auto-activation triggers, enable/disable
- **Hooks** - Behavior customization (protected branches, timeouts, etc.)
- **All installed plugins** - Unified configuration in one file

## Your Task

Execute this workflow intelligently based on what configuration files exist:

### Step 1: Detect Existing Configuration

Check for these files:

- **New format**: `.claude/super-claude-config.json`
- **Legacy format**: `.claude/skills/skill-rules.json`

### Step 2: Determine Strategy (Smart Routing)

**CASE 1: No configuration files exist (Clean Slate)**

- Generate `.claude/super-claude-config.json` from all plugin defaults
- No questions needed, just create it
- Skip to Step 4 (Generation)

**CASE 2: Only legacy config exists**

Use AskUserQuestion:

```json
{
  "questions": [
    {
      "question": "Found legacy skill-rules.json configuration. How should we handle it?",
      "header": "Migration",
      "multiSelect": false,
      "options": [
        {
          "label": "Migrate to new format",
          "description": "Convert to super-claude-config.json and create backup (.bak file)"
        },
        {
          "label": "Keep legacy format",
          "description": "Create new config separately (both will work, legacy shows deprecation warning)"
        }
      ]
    }
  ]
}
```

Actions based on answer:

- **"Migrate to new format"**: Follow Migration workflow (Step 3a)
- **"Keep legacy format"**: Generate new config only, don't touch legacy (Step 4)

**CASE 3: Only new config exists**

Check if new plugin defaults are available:

```typescript
// Pseudo-code logic
const current = loadJson('.claude/super-claude-config.json');
const allPluginDefaults = discoverPluginDefaults(); // from plugins/*/super-claude-config.json
const newAdditions = computeNewAdditions(current, allPluginDefaults);

if (newAdditions.isEmpty()) {
  // No updates needed
  console.log('✓ Configuration is up to date (all plugins configured)');
  return;
}
```

If new defaults found, use AskUserQuestion:

```json
{
  "questions": [
    {
      "question": "Found ${count} new configuration options. Add them to your config?",
      "header": "Update",
      "multiSelect": false,
      "options": [
        {
          "label": "Add new defaults",
          "description": "Add ${summary} while preserving all your customizations"
        },
        {
          "label": "Skip for now",
          "description": "Don't update (you can run /workflow:configure again later)"
        }
      ]
    }
  ]
}
```

Actions based on answer:

- **"Add new defaults"**: Merge new defaults (Step 3b)
- **"Skip for now"**: Exit without changes

**CASE 4: Both configs exist**

Use AskUserQuestion:

```json
{
  "questions": [
    {
      "question": "Both legacy and new configuration files exist. What should we do?",
      "header": "Conflict",
      "multiSelect": false,
      "options": [
        {
          "label": "Merge into new config",
          "description": "Import legacy overrides into super-claude-config.json (creates backup)"
        },
        {
          "label": "Update new config only",
          "description": "Ignore legacy file and just update super-claude-config.json"
        },
        {
          "label": "Keep both separate",
          "description": "Don't merge (both will be loaded, legacy shows deprecation warning)"
        }
      ]
    }
  ]
}
```

Actions based on answer:

- **"Merge into new config"**: Migration + merge workflow (Step 3a)
- **"Update new config only"**: Update new config, ignore legacy (Step 3b)
- **"Keep both separate"**: Exit without changes

### Step 3a: Migration Workflow

**Convert legacy skill-rules.json to new format:**

```typescript
function migrateLegacyConfig(legacyPath: string): ProjectConfig {
  const legacy = JSON.parse(fs.readFileSync(legacyPath, 'utf8'));
  const migrated: ProjectConfig = {};

  // Legacy format has:
  // - plugin.namespace (e.g., "meta")
  // - skills.{skillName}
  // - overrides.disabled (array of "namespace/skillName")

  const namespace = legacy.plugin.namespace;

  if (!migrated[namespace]) {
    migrated[namespace] = { skills: {}, hooks: {} };
  }

  // Convert disabled skills
  if (legacy.overrides?.disabled) {
    for (const fullName of legacy.overrides.disabled) {
      const [ns, skillName] = fullName.split('/');
      if (ns === namespace) {
        migrated[namespace].skills[skillName] = { enabled: false };
      }
    }
  }

  // Convert skill overrides (if any custom triggers, priorities, etc.)
  for (const [skillName, skillData] of Object.entries(legacy.skills || {})) {
    if (!migrated[namespace].skills[skillName]) {
      migrated[namespace].skills[skillName] = {};
    }

    // Preserve custom triggers if they exist
    if (skillData.promptTriggers) {
      migrated[namespace].skills[skillName].triggers = {
        keywords: skillData.promptTriggers.keywords || [],
        patterns: skillData.promptTriggers.intentPatterns || [],
      };
    }
  }

  return migrated;
}
```

**Workflow:**

1. Read `.claude/skills/skill-rules.json`
2. Convert to new format using migration logic above
3. Create backup: `cp .claude/skills/skill-rules.json .claude/skills/skill-rules.json.bak`
4. Load all plugin defaults
5. Deep merge: `plugin defaults → migrated overrides → existing new config (if any)`
6. Write to `.claude/super-claude-config.json`

### Step 3b: Update Existing Config

**Add only NEW plugins/hooks while preserving ALL user customizations:**

```typescript
function addNewDefaults(
  current: ProjectConfig,
  allDefaults: Record<string, PluginConfig>,
): ProjectConfig {
  const result = { ...current };

  for (const [pluginName, pluginDefaults] of Object.entries(allDefaults)) {
    if (!result[pluginName]) {
      // Brand new plugin - add entire config
      result[pluginName] = {
        skills: pluginDefaults.skills || {},
        hooks: pluginDefaults.hooks || {},
      };
    } else {
      // Existing plugin - add only NEW skills/hooks

      // Add new skills
      if (pluginDefaults.skills) {
        result[pluginName].skills = result[pluginName].skills || {};
        for (const [skillName, skillConfig] of Object.entries(
          pluginDefaults.skills,
        )) {
          if (!result[pluginName].skills[skillName]) {
            // Only add if doesn't exist (preserve user customizations)
            result[pluginName].skills[skillName] = skillConfig;
          }
        }
      }

      // Add new hooks
      if (pluginDefaults.hooks) {
        result[pluginName].hooks = result[pluginName].hooks || {};
        for (const [hookName, hookConfig] of Object.entries(
          pluginDefaults.hooks,
        )) {
          if (!result[pluginName].hooks[hookName]) {
            // Only add if doesn't exist (preserve user customizations)
            result[pluginName].hooks[hookName] = hookConfig;
          }
        }
      }
    }
  }

  return result;
}
```

### Step 4: Generate Configuration

**Discover all plugin defaults:**

1. Find all `plugins/*/super-claude-config.json` files in the repository
2. Extract `skills` and `hooks` from each plugin's config
3. Build a map of plugin-name → { skills, hooks }

**Generate the configuration file:**

Use this EXACT template structure - do NOT modify the `$schema` path or repo URL:

```json
{
  "$schema": "../../.claude-plugin/super-claude-config.schema.json",
  "_comment": [
    "Super Claude Plugin Configuration",
    "",
    "This file controls plugin behavior for this project.",
    "Configuration priority: this file > plugin defaults > environment variables",
    "",
    "Common customizations:",
    "  • Disable a skill: Set 'enabled': false",
    "  • Change protected branches: Modify workflow.hooks.gitCommitGuard.protectedBranches",
    "  • Add branch prefixes: Modify workflow.hooks.branchNameValidator.allowedPrefixes",
    "  • Customize triggers: Add/modify 'keywords' or 'patterns' arrays",
    "",
    "Changes take effect immediately (no restart needed).",
    "Documentation: https://github.com/jbabin91/super-claude"
  ],
  "workflow": {
    "skills": {},
    "hooks": {}
  },
  "meta": {
    "skills": {},
    "hooks": {}
  }
}
```

**CRITICAL: Merge discovered defaults into this template structure:**

1. For each plugin discovered, add a top-level key with that plugin's name
2. Populate `skills` and `hooks` from the discovered defaults
3. Keep the `$schema` and `_comment` exactly as shown above
4. Format with Prettier using these rules:
   - **NO blank lines between object properties**
   - 2-space indentation
   - Double quotes for strings
   - Trailing commas where allowed

**Example after merging (if testing plugin discovered):**

```json
{
  "$schema": "../../.claude-plugin/super-claude-config.schema.json",
  "_comment": [
    "Super Claude Plugin Configuration",
    "",
    "This file controls plugin behavior for this project.",
    "Configuration priority: this file > plugin defaults > environment variables",
    "",
    "Common customizations:",
    "  • Disable a skill: Set 'enabled': false",
    "  • Change protected branches: Modify workflow.hooks.gitCommitGuard.protectedBranches",
    "  • Add branch prefixes: Modify workflow.hooks.branchNameValidator.allowedPrefixes",
    "  • Customize triggers: Add/modify 'keywords' or 'patterns' arrays",
    "",
    "Changes take effect immediately (no restart needed).",
    "Documentation: https://github.com/jbabin91/super-claude"
  ],
  "workflow": {
    "skills": {},
    "hooks": {
      "gitCommitGuard": {
        "enabled": false,
        "protectedBranches": ["main", "master"],
        "bypassEnvVar": "SKIP_COMMIT_GUARD"
      },
      "branchNameValidator": {
        "enabled": false,
        "allowedPrefixes": [
          "feat",
          "fix",
          "chore",
          "docs",
          "test",
          "refactor",
          "perf",
          "build",
          "ci",
          "revert",
          "style"
        ],
        "allowedBranches": ["main", "master", "develop"]
      },
      "typeChecker": {
        "enabled": true,
        "timeout": 2000
      },
      "sessionChecklist": {
        "enabled": true
      }
    }
  },
  "meta": {
    "skills": {
      "skill-creator": {
        "enabled": true,
        "triggers": {
          "keywords": ["create skill", "new skill", "skill development"],
          "patterns": ["(create|add|generate|build).*?skill"]
        }
      },
      "hook-creator": {
        "enabled": true,
        "triggers": {
          "keywords": ["create hook", "new hook", "hook development"],
          "patterns": ["(create|add|generate|build).*?hook"]
        }
      }
    },
    "hooks": {}
  },
  "testing": {
    "skills": {
      "test-runner": {
        "enabled": true,
        "triggers": {
          "keywords": ["run tests", "test"],
          "patterns": ["(run|execute).*?tests?"]
        }
      }
    },
    "hooks": {}
  }
}
```

### Step 5: Show Summary

Provide clear feedback based on what was done:

**For clean slate generation:**

```txt
✓ Created .claude/super-claude-config.json

Configured ${pluginCount} plugins:
  • workflow (${skillCount} skills, ${hookCount} hooks)
  • meta (${skillCount} skills, ${hookCount} hooks)
  ...

Next steps:
  1. Open .claude/super-claude-config.json
  2. Customize settings for your project
  3. Changes take effect immediately (no restart needed)

Common customizations:
  • Disable skill: Set "enabled": false
  • Change protected branches: Modify workflow.hooks.gitCommitGuard.protectedBranches
  • Add branch prefixes: Modify workflow.hooks.branchNameValidator.allowedPrefixes

Documentation: See docs/guides/plugin-configuration.md
```

**For migration:**

```txt
✓ Migrated legacy configuration

Actions taken:
  • Created backup: .claude/skills/skill-rules.json.bak
  • Migrated overrides → .claude/super-claude-config.json
  • Merged with plugin defaults

Your customizations were preserved:
  - meta/skill-creator: disabled
  - Custom triggers for hook-creator

You can safely delete .claude/skills/skill-rules.json after verification.
The new config will be loaded automatically.
```

**For update:**

```txt
✓ Updated .claude/super-claude-config.json

Added new defaults:
  + Plugin: testing (3 skills, 2 hooks)
  + Hook: workflow/sessionChecklist
  + Hook: workflow/typeChecker

Your existing customizations were preserved:
  - workflow/gitCommitGuard.protectedBranches: ["main", "production"]
  - meta/skill-creator.enabled: false
```

**For up-to-date:**

```txt
✓ Configuration is up to date

All ${pluginCount} installed plugins are configured.
No new defaults available.

To reset to plugin defaults: Delete .claude/super-claude-config.json and run this command again.
```

## Error Handling

1. **Cannot create .claude/ directory**
   - Check permissions
   - Suggest: `chmod +w .claude`

2. **Plugin defaults not found**
   - List plugins with missing configs
   - Suggest: Check plugin installation

3. **Invalid JSON in existing config**
   - Show parse error
   - Offer to backup and regenerate

4. **File write fails**
   - Show specific error
   - Check disk space and permissions

## Important Notes

- **Always preserve user customizations** - Never overwrite unless user explicitly confirms
- **Create backups** - Always create `.bak` files before modifying
- **Deep merge strategy** - User values always win over defaults
- **Idempotent** - Safe to run multiple times
- **No restart needed** - Config loader reads on every hook execution

## Testing Checklist

After implementation, verify:

- [ ] Clean slate generation works
- [ ] Legacy migration creates backup
- [ ] Update adds only new defaults
- [ ] Conflict resolution offers all choices
- [ ] User customizations are never lost
- [ ] AskUserQuestion shows clear options
- [ ] Summary messages are accurate
- [ ] Generated JSON is valid and formatted