SuperClaude-Org/SuperClaude_Framework

[BUG] README Documentation Promises Non-Existent TypeScript Plugin System (v2.0+)

Opened this issue · 2 comments

luisangelq commented

The README claims SuperClaude v2.0+ uses TypeScript plugins with project-local auto-detection, but this feature does not exist in any branch. I've spent several hours trying to follow the installation instructions only to discover this is vaporware.

Evidence of Missing Implementation

1. README Claims (Lines 1-50)

Quick Installation
Project-Local Plugin (Recommended)
SuperClaude v2.0+ uses TypeScript plugins with project-local auto-detection:

# Clone repository
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework

# Start Claude Code in this directory
claude

That's it! .claude-plugin/ is auto-detected and PM Agent activates on session start.

Key Claims:

  • "TypeScript plugins"
  • "Project-local auto-detection"
  • ".claude-plugin/ is auto-detected"
  • "3 core plugins: PM Agent, Research, Index"
  • "New: /pm, /research, /index-repo (3 plugin commands)"

2. Actual State in Repository

Checked all branches:

# master branch (v4.1.6)
ls .claude-plugin/
# ls: .claude-plugin/: No such file or directory

# SuperClaude-v2 branch
git checkout SuperClaude-v2
ls .claude-plugin/
# ls: .claude-plugin/: No such file or directory

# SuperClaude-v3 branch
git checkout SuperClaude-v3
ls .claude-plugin/
# ls: .claude-plugin/: No such file or directory

Build script fails:

make build-plugin
# Building SuperClaude plugin from unified sources...
# FileNotFoundError: [Errno 2] No such file or directory:
# '/Users/xxx/SuperClaude_Framework/plugins/superclaude/manifest/metadata.json'

No TypeScript files found:

find . -name "*.ts" | grep -v node_modules
# plugins/superclaude/skills/confidence-check/confidence.ts  # Only 1 file

3. Cross-Reference with Issue #419

Issue #419 explicitly shows this is a PROPOSAL (not implemented):

  • Title: "Add Native Plugin System Support for SuperClaude Installation"
  • Status: OPEN (created Oct 13, 2025)
  • Content: 8-week implementation roadmap
  • Comment by @Utakata: Detailed migration plan starting from v4 → v5
  • Comment by @mithun50: "@Utakata working on this plugin" (assigned, but not done)

This proves the feature is planned, not released.

Time Wasted

I spent 3-4 hours:

  1. Backing up current v4.0.9 installation (~30min)
  2. Cloning fresh repository (~5min)
  3. Trying to build plugins (~1hr)
  4. Checking all branches (~30min)
  5. Searching for missing files (~1hr)
  6. Cross-referencing issues and docs (~1hr)

Only to discover the feature doesn't exist.

What's Actually Available

Current version: v4.1.6

  • Architecture: Traditional slash commands (.claude/commands/)
  • Installation: pip install superclaude or ./install.sh
  • Commands: /sc:* (not /pm, /research, /index-repo)
  • No TypeScript plugins
  • No .claude-plugin/ directory

Questions for Maintainers

  1. Why does the README document a non-existent feature?

    • Is this a documentation bug?
    • Was the README updated prematurely for v5.0?

  2. What's the actual timeline for TypeScript plugins?

    • Issue #419 mentions 8-week roadmap (starting when?)
    • Is this targeting v5.0?

  3. How should users install SuperClaude NOW?

    • Should we use v4.1.6 with traditional installation?
    • Should we wait for v5.0 plugin system?

  4. Why wasn't this caught in CI/CD?

    • Installation instructions should be tested automatically
    • Build script failures should block merges

Requested Actions

Immediate (Critical)

  1. Fix README.md

    • Remove references to TypeScript plugins until implemented
    • Document actual v4.1.6 installation (slash commands)
    • Add clear "Coming Soon" section for v5.0 plugin system

  2. Add prominent warning:

    > **IMPORTANT**: The TypeScript plugin system described below is
> not yet available (planned for v5.0). For current installation
> instructions, see [v4.1.6 Installation](#v416-installation).

  3. Update issue #466

    • Close as duplicate of this issue
    • Provide workaround instructions

Short-term

  1. Create v5.0 milestone

    • Move issue #419 to this milestone
    • Set clear target date or "when ready" status

  2. Add CI tests

    • Test README installation instructions
    • Verify plugin build scripts work before merge

Long-term

  1. Documentation review process
    • Prevent documenting unimplemented features
    • Add "Status" badges (Stable, Beta, Planned)

Related Issues

  • #419 - Plugin system proposal (OPEN, assigned but not implemented)
  • #466 - Missing .claude-plugin directory (duplicate of this issue)

Suggested Interim README

## Installation

### Current Stable Version (v4.1.6)

SuperClaude currently uses slash commands. Install via:

**Option 1: pip/pipx**
\```bash
pip install superclaude
superclaude install
\```

**Option 2: Direct installation**
\```bash
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
./install.sh
\```

### Coming in v5.0 (Not Available Yet)

We're working on TypeScript plugin support (see #419). When released, installation will be:

\```bash
/plugin marketplace add SuperClaude-Org/superclaude-plugin-marketplace
/plugin install superclaude
\```

**Status**: In development, no ETA yet.

I appreciate the work going into SuperClaude—it's a great framework. However, documenting features that don't exist wastes users' time and damages trust.

Please update the README urgently to reflect the actual state of the project.

@mithun50 @Utakata @daniil-shumko (Issue #419 participants)

Utakata commented

Hi luisangelq,

Thank you for sharing your experience with us in such a clear and detailed way.

When I read that you spent several hours attempting to follow our README.md instructions, I felt a deep sense of regret and concern. It sounds like you were feeling frustrated and let down, especially when you needed accurate and reliable information to get started with the project efficiently.

We have a strong need to ensure that our documentation is a trustworthy and supportive resource for our community, and it's clear from your report that we fell short of that. Your feedback was a gift, as it helped us see the gap between our intentions and the actual experience of a user.

To address the need for clarity and trustworthiness, I have just submitted a patch that corrects the README.md. The file now reflects the project's current stable version (v4.2.0), removes the misleading information about the unimplemented plugin system, and provides accurate installation instructions.

We are truly grateful for the care and energy you invested in writing your report. You have helped us better serve our community and align our actions with our values.

We hope this action helps restore your confidence in the project.

Utakata@4921845

frankbria commented

@Utakata Is that work complete? Because as far as I see, the README.md in the main branch still reflects the non-existent .claude-plugin directory.