{
  "id": "page:docs-agent-mux-archive-superpowers-specs-2026-04-12-documentation-plugin-system-overhaul-design",
  "_kind": "Page",
  "_file": "wiki/docs/agent-mux/archive/superpowers/specs/2026-04-12-documentation-plugin-system-overhaul-design.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/agent-mux/archive/superpowers/specs/2026-04-12-documentation-plugin-system-overhaul-design.md",
    "sourceKind": "repo-docs",
    "title": "Documentation and Plugin System Overhaul",
    "displayName": "Documentation and Plugin System Overhaul",
    "slug": "docs/agent-mux/archive/superpowers/specs/2026-04-12-documentation-plugin-system-overhaul-design",
    "articlePath": "wiki/docs/agent-mux/archive/superpowers/specs/2026-04-12-documentation-plugin-system-overhaul-design.md",
    "article": "\n# Documentation and Plugin System Overhaul\n\n## Overview\n\nThis design addresses multiple documentation quality issues and implements a proper separation between plugin management and MCP server management in the agent-mux CLI system.\n\n## Problems Being Solved\n\n1. **Outdated Installation Instructions**: Agent docs show direct npm installation instead of `amux install`\n2. **Misleading Plugin Management**: Current docs conflate plugins with MCP servers\n3. **Broken Links**: Links are broken on docs homepage and throughout documentation  \n4. **No Link Monitoring**: No automated prevention of broken links in future changes\n5. **Command Structure Confusion**: `amux plugins` actually manages MCPs, not true plugins\n\n## Approach: Infrastructure-First\n\n**Sequence:**\n1. Set up automated link checking in CI (mlc integration)\n2. Implement new plugin/MCP command structure  \n3. Update all documentation systematically\n4. Update specs and tests\n\n**Why this approach**: Link checking prevents introducing new broken links during extensive doc updates, and proper command implementation guides accurate documentation.\n\n## Design\n\n### 1. Automated Link Checking Infrastructure\n\n**CI Integration:**\n- Add `mlc` (Markup Link Checker) GitHub Action to the docs CI workflow\n- Configure to run on all PRs and main branch pushes that touch documentation\n- Set to fail builds on broken links (strict mode)\n\n**Configuration:**\n- Create `.mlcconfig` file to:\n  - Exclude external domains that frequently timeout (optional allowlist approach)\n  - Set timeout values appropriate for CI\n  - Configure to check both markdown files and generated HTML\n\n**Docs Build Integration:**\n- Ensure the docs build treats broken links as errors\n- This ensures local development catches broken links before CI\n\n**Testing Strategy:**\n- Test against current documentation to establish baseline broken links\n- Fix any existing broken links as prerequisite\n- Add mlc check to local development workflow (`npm run link-check`)\n\n**Expected Outcome:** Any documentation changes will automatically be validated for broken links, preventing regression during extensive documentation updates.\n\n### 2. Plugin/MCP Command Structure Implementation\n\n**New Command Architecture:**\n- **`amux mcp`** - Manage Model Context Protocol servers per agent\n- **`amux plugin`** - Manage full plugins through agent-native systems\n\n**MCP Commands (Rename existing `amux plugins`):**\n\n```bash\n# Global MCP management\namux mcp list <agent>                    # List installed MCPs for agent\namux mcp install <agent> <mcp-server>    # Install MCP server for agent\namux mcp uninstall <agent> <mcp-server>  # Remove MCP server for agent\n\n# Project-level MCP management (new)\namux mcp list <agent> --project         # List project-specific MCPs\namux mcp install <agent> <mcp-server> --project  # Install to project scope\n```\n\n**Note**: MCP commands will require additional implementation beyond the basic commands shown above. The full MCP command API design (including configuration management, enable/disable states, and config file handling) will be detailed in a separate technical specification during implementation.\n\n**Plugin Commands (New - delegate to native harness commands):**\n\n```bash\namux plugin list <agent>                 # Calls: claude plugins list, gemini extensions list, etc.\namux plugin install <agent> <plugin>     # Calls: claude plugins install <plugin>, etc.\namux plugin enable <agent> <plugin>      # Calls: claude plugins enable <plugin>, etc.  \namux plugin disable <agent> <plugin>     # Calls: claude plugins disable <plugin>, etc.\namux plugin marketplace <agent> [cmd]    # Calls: claude plugins marketplace [cmd], etc.\n```\n\n**Agent Plugin System Support:**\n- **Claude**: Full plugin system with marketplace\n- **Gemini**: Extension system for prompts, MCP servers, commands, themes, hooks\n- **Codex**: Plugin directory with @plugin-creator skill\n- **Cursor**: Hook support (Claude Code compatible), MCP-only CLI  \n- **GitHub Copilot**: GitHub Copilot CLI plugin marketplace with agents/skills/hooks/MCP packages\n- **OpenCode**: Three-tier extensibility (skills/agents/plugins)\n\n**Error Handling:**\nFor agents without native plugin systems, return clear error: \"Plugin management not supported for `{agent}`. Use 'amux mcp' for MCP servers.\"\n\n### 3. Systematic Documentation Updates\n\n**Installation Instructions (All Agent Docs):**\nReplace direct npm installs with:\n```bash\n# Before:\nnpm install -g @anthropic-ai/claude-code\n\n# After:  \namux install claude\n```\n\n**Plugin Management Sections (All Agent Docs):**\nReplace existing incorrect MCP-focused sections with agent-appropriate content:\n\n```bash\n# For agents WITH native plugin systems (Claude, Gemini, Cursor, etc.):\namux plugin install <agent> <plugin>\namux plugin list <agent>\namux plugin marketplace <agent>\n\n# For MCP servers (all agents):\namux mcp install <agent> <mcp-server>\namux mcp list <agent>\n```\n\n**New Sections to Add:**\n- Clear distinction between \"Plugins\" vs \"MCP Servers\" in each agent doc\n- Examples showing both plugin installation and MCP server installation\n- Links to agent-specific plugin marketplaces where available\n\n**Agent-Specific Variations:**\n- **Claude/Copilot/Cursor**: Full plugin ecosystem documentation\n- **Gemini**: Extension-focused language and examples\n- **OpenCode**: Three-tier system explanation (skills/agents/plugins)\n- **Agents without plugin systems**: MCP-only documentation, clear explanation of limitations\n\n**Scope:** Update all 12 agent documentation files plus any tutorial/reference docs that mention installation or plugin management.\n\n### 4. Specs and Tests Updates\n\n**Specification Updates:**\n- Document `amux mcp` command API with all configuration nuances\n- Document `amux plugin` command delegation patterns per agent\n- Update CLI reference documentation with new command structure\n- Create decision matrix: when to use plugins vs MCP servers\n- Update TypeScript interfaces for new command structures\n- Document agent capability detection (supports plugins vs MCP-only)\n- Specify error handling patterns for unsupported operations\n\n**Test Coverage:**\n\n**Unit Tests:**\n- Test `amux mcp` command variations (global/project scopes, configurations)\n- Test `amux plugin` delegation to each agent's native commands\n- Test error handling for agents without plugin support\n- Test command parsing and argument validation\n\n**Integration Tests:**\n- Test actual delegation to `claude plugins`, `gemini extensions`, etc.\n- Test MCP configuration file manipulation (global vs project)\n- Test graceful failures when agent CLIs are not installed\n\n**Documentation Tests:**\n- Automated link checking in CI (using mlc)\n- Test that all installation examples use `amux install` format\n- Validate plugin vs MCP distinction in all agent docs\n\n## Success Criteria\n\n1. **Zero broken links** in documentation with automated prevention\n2. **Clear separation** between plugins and MCP servers in CLI and docs\n3. **Consistent installation instructions** across all agent documentation\n4. **Working plugin delegation** to each agent's native plugin system\n5. **Comprehensive test coverage** for new command structures\n6. **Updated specifications** reflecting new architecture\n\n## Implementation Notes\n\n- **No backward compatibility** - existing `amux plugins` commands will be replaced entirely\n- **MCP configuration complexity** will require detailed technical specification during implementation (configuration file formats, enable/disable states, global vs project scoping)\n- **Agent capability detection** will check for native plugin command availability (e.g., test if `claude plugins --help` succeeds) to determine plugin vs MCP-only support\n- **Link checking integration** must not significantly slow CI pipeline\n\n## Dependencies\n\n- **mlc (Markup Link Checker)** for automated link validation\n- **Native agent CLIs** must be installed for plugin command delegation to work\n- **Agent-specific plugin systems** vary significantly in capabilities and command structure\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-agent-mux-archive-superpowers",
      "to": "page:docs-agent-mux-archive-superpowers-specs-2026-04-12-documentation-plugin-system-overhaul-design",
      "kind": "contains_page"
    }
  ]
}