Initial commit
This commit is contained in:
Zhongwei Li
510
commands/configure.md
Normal file
510
commands/configure.md
Normal file
@@ -0,0 +1,510 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user