[FEATURE] Plugin Command Visibility Filtering / Organizational Modes

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Problem Statement

Plugin developers currently have no way to control which commands appear in Claude Code's autocomplete. As plugins grow in complexity and command count, they create significant UX problems:

• Autocomplete Overload: Users typing /plugin-name... see dozens of commands flooding the screen
• Cognitive Load: New users are overwhelmed trying to find the right command among 30+ options
• No Progressive Disclosure: Cannot hide advanced/internal commands from beginners
• Poor Scalability: Rich plugins must choose between limited functionality or poor UX

Real-world example: The SpecSwarm plugin has 33 commands. When users type /specswarm:, the autocomplete fills the entire terminal, making it difficult to find the right command for their task.

Proposed Solution

Proposed Solution

Add native support for command visibility filtering via:

1. New Frontmatter Field: visibility

Allow command authors to categorize commands by visibility level:

---
description: Build complete feature from specification
visibility: public  # Options: public | internal | experimental
---

2. Plugin-Level Mode Configuration

Let plugins define visibility modes in their config:

// ~/.claude/plugins/<plugin-name>/config.json
{
  "commandVisibilityMode": "basic",
  "visibilityModes": {
    "basic": {
      "description": "Essential commands for daily work",
      "visible": ["public"]
    },
    "advanced": {
      "description": "Full workflow control",
      "visible": ["public", "internal"]
    },
    "all": {
      "description": "Everything including experimental",
      "visible": ["public", "internal", "experimental"]
    }
  }
}

3. Runtime Filtering

Claude Code's command discovery system would:

1. Read the current commandVisibilityMode from plugin config
2. Filter commands based on their visibility metadata
3. Only show commands that match the active mode's visible list
4. Still allow hidden commands to be called directly (they just don't appear in autocomplete)

Alternative Solutions

Alternative Solutions

1. Use disable-model-invocation: true - Only prevents auto-invocation, doesn't hide from autocomplete
2. Create multiple separate plugins - Fragments functionality, confusing for users
3. Physical file manipulation - Requires plugin restart, complex state management
4. Documentation only - Relies on user discipline, doesn't solve the UX problem

None of these alternatives provide the clean UX that native visibility filtering enables.

Priority

Medium - Would be very helpful

Feature Category

CLI commands and flags

Use Case Example

Use Case Example

I built a working prototype implementing this pattern for the SpecSwarm plugin:

Command Distribution:

• 9 PUBLIC commands - Core orchestrators (build, fix, ship, etc.)
• 19 INTERNAL commands - Granular workflow steps (specify, plan, tasks, implement)
• 5 EXPERIMENTAL commands - Advanced features (orchestrate, refactor, deprecate)

User Workflows:

Beginner Mode ("basic"):

User types: /specswarm:
Shows: 9 core commands
Result: Clean, focused autocomplete

Power User Mode ("advanced"):

User types: /specswarm:
Shows: 28 commands (public + internal)
Result: Full manual control over workflows

Developer Mode ("all"):

User types: /specswarm:
Shows: All 33 commands
Result: Maximum flexibility

Mode Switching:

/specswarm:mode basic     # Switch to beginner mode
/specswarm:mode advanced  # Switch to power user mode
/specswarm:mode all       # Show everything

Prototype Implementation: https://github.com/MartyBonacci/specswarm/tree/modes

Additional Context

Additional Context

Why This Matters

For Plugin Developers:

• ✅ Can build rich, comprehensive plugins without UX penalties
• ✅ Progressive disclosure: beginners see simple interface, power users get full control
• ✅ Better command organization and discoverability
• ✅ Can hide internal/experimental commands until needed

For Plugin Users:

• ✅ 75% reduction in autocomplete clutter (SpecSwarm: 33 → 9 commands)
• ✅ Clearer command purpose and organization
• ✅ Easier to learn new plugins
• ✅ Can opt-in to advanced features when ready

For the Claude Code Ecosystem:

• ✅ Enables more sophisticated plugins without sacrificing UX
• ✅ Standard pattern for command organization across plugins
• ✅ Scales as plugins grow in complexity
• ✅ Maintains backward compatibility (default: all visible)

---

Technical Implementation Notes

Frontmatter Processing:

Add visibility to the list of recognized frontmatter fields (alongside description, allowed-tools, model, etc.):

interface CommandFrontmatter {
  description: string;
  visibility?: 'public' | 'internal' | 'experimental' | string;
  // ... existing fields
}

Default behavior: If visibility is not specified, treat as 'public' (backward compatible).

Config Schema:

Extend plugin config to support mode definitions:

interface PluginConfig {
  commandVisibilityMode?: string;  // Active mode name
  visibilityModes?: {
    [modeName: string]: {
      description: string;
      visible: string[];  // List of visibility levels to show
    }
  };
  // ... existing config
}

Discovery Filter:

During command discovery, apply visibility filter:

function discoverCommands(plugin: Plugin): Command[] {
  const commands = scanCommandFiles(plugin);
  const config = loadPluginConfig(plugin);

  if (!config.commandVisibilityMode) {
    return commands; // No filtering if mode not set
  }

  const mode = config.visibilityModes[config.commandVisibilityMode];
  const visibleLevels = new Set(mode.visible);

  return commands.filter(cmd =>
    !cmd.visibility || visibleLevels.has(cmd.visibility)
  );
}

---

Real-World Impact

Before (without visibility filtering):

User types: /specswarm:
Autocomplete shows:
  /specswarm:analyze
  /specswarm:analyze-quality
  /specswarm:bugfix
  /specswarm:build
  /specswarm:checklist
  /specswarm:clarify
  /specswarm:complete
  /specswarm:constitution
  /specswarm:coordinate
  /specswarm:deprecate
  /specswarm:fix
  /specswarm:hotfix
  /specswarm:impact
  /specswarm:implement
  /specswarm:init
  /specswarm:metrics
  /specswarm:metrics-export
  /specswarm:mode
  /specswarm:modify
  /specswarm:orchestrate
  /specswarm:orchestrate-feature
  /specswarm:orchestrate-validate
  /specswarm:plan
  /specswarm:refactor
  /specswarm:release
  /specswarm:rollback
  /specswarm:security-audit
  /specswarm:ship
  /specswarm:specify
  /specswarm:suggest
  /specswarm:tasks
  /specswarm:upgrade
  /specswarm:validate

User: "Which one do I need?" 😰

After (with visibility filtering in "basic" mode):

User types: /specswarm:
Autocomplete shows:
  /specswarm:build
  /specswarm:fix
  /specswarm:init
  /specswarm:metrics
  /specswarm:mode
  /specswarm:modify
  /specswarm:ship
  /specswarm:suggest
  /specswarm:upgrade

User: "Clear and focused!" 😊

---

Backward Compatibility

• ✅ No breaking changes: Existing plugins work unchanged
• ✅ Opt-in feature: Only affects plugins that add visibility metadata
• ✅ Default to visible: Commands without visibility field show normally
• ✅ Graceful degradation: If mode not set, all commands appear

---

Request

Please consider adding native command visibility filtering to Claude Code's plugin system. This would:

1. Enable better UX for complex plugins
2. Establish a standard pattern for command organization
3. Scale the plugin ecosystem sustainably
4. Maintain full backward compatibility

Prototype available: The SpecSwarm plugin has a complete working implementation (metadata, config system, mode switching command, documentation) at https://github.com/MartyBonacci/specswarm/tree/modes - ready to demonstrate the feature when Claude Code supports it.

Happy to provide additional details, code examples, or help with implementation!

---

Metadata

• Related: Plugin command management and organization
• Category: Plugin System Enhancement
• Priority: Medium-High (impacts plugin ecosystem scalability)
• Implementation Complexity: Low-Medium (mostly frontmatter parsing and filtering logic)