gh-jbabin91-super-claude-plugins-workflow/commands/configure.md

name, description, version

name	description	version
configure	Generate or update project-level plugin configuration with smart migration	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:

{
  "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:

// 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:

{
  "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:

{
  "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:

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:

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:

{
  "$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):

{
  "$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:

✓ 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:

✓ 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:

✓ 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:

✓ 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