External/SuperClaude
1
0
Fork 0
mirror of https://github.com/SuperClaude-Org/SuperClaude_Framework.git synced 2025-12-17 17:56:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

Claude/fix readme plugin docs 011 cv2 lk n gko6wzm tfn dmnrm (#478)

Browse Source 
* Fix(docs): READMEをプロジェクトの現状に合わせて修正

README.mdに、未実装のTypeScriptプラグインシステム（v2.0+）に関するドキュメントが含まれていました。これにより、インストールを試みるユーザーに深刻な混乱を招き、時間と第一印象を損なう原因となっていました。

このコミットは、README.mdをプロジェクトの現状（v4.2.0）を正確に反映するように修正します。

- 存在しないTypeScriptプラグインに関する誤解を招く指示や機能説明をすべて削除しました。
- インストールセクションの冒頭に、プラグインシステムが将来のv5.0で計画されている機能であることを明確にするための警告文を追加しました。
- 現在の安定バージョンに対して、`pipx`またはgitクローンを使用する明確で検証済みのインストール手順を提供しました。
- 未実装の機能に基づいていた古いセクション（「V1.xからのアップグレード」やプラグインに関する「トラブルシューティング」など）を削除しました。
- 「What's New」セクションを、現在のv4.2リリースに関連するものに更新しました。

この変更により、ユーザーから報告された問題が解決され、ドキュメントが新規および既存のコントリビューターにとって信頼できるリソースであることが保証されます。

ユーザーのフィードバックに対応し、根本原因を解決することで間接的に課題#466をクローズします。
関連課題: #419 (プラグインシステムの提案)

* docs: Fix misleading plugin system documentation

Fixes multiple issues reported in GitHub where users wasted hours
following installation instructions for non-existent features.

Changes:
- README.md: Correct version from 4.2.0 to 4.1.6 (matches VERSION file)
- README.md: Already had warning about v5.0 plugin system (no change needed)
- CLAUDE.md: Add prominent warnings that TypeScript plugin system does NOT exist
- CLAUDE.md: Clarify .claude-plugin/ directory is planned for v5.0, not v4.1.6
- CLAUDE.md: Document actual v4.1.6 installation method (pipx/install.sh)
- CLAUDE.md: List features that DON'T work yet (plugin commands, marketplace, etc.)

Background:
- Issue #419: Plugin system is a PROPOSAL, not implemented
- .claude-plugin/ directory does not exist in any branch
- Current v4.1.6 uses slash commands via `superclaude install`
- TypeScript plugin system planned for v5.0 (no ETA)

This prevents users from wasting 3-4 hours trying to use features
that don't exist, as reported by multiple users.

Refs: #419

* docs: Fix version numbers in i18n README files

Update version badges in localized README files to match actual version.

Changes:
- README-ja.md: 4.1.5 → 4.1.6
- README-zh.md: 4.1.5 → 4.1.6
- README-kr.md: 4.1.5 → 4.1.6

All localized READMEs now correctly reflect the current version from
the VERSION file (4.1.6).

Note: These files did not contain misleading plugin system documentation,
only the version number needed correction.

---------

Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Utakata 2025-11-12 01:30:49 +09:00 committed by GitHub
parent 0ef8ea8139
commit bec0b0c3e3
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
5 changed files with 124 additions and 164 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

132
CLAUDE.md
View File

@ -18,20 +18,19 @@ uv run python script.py # Execute scripts
## 📂 Project Structure ## 📂 Project Structure
**Dual-language architecture**: TypeScript plugins for Claude Code integration + Python package for testing/CLI tools. > **⚠️ IMPORTANT**: The `.claude-plugin/` directory and TypeScript plugin system described in older docs **DO NOT EXIST** in v4.1.6.
> This is planned for v5.0 (see [issue #419](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues/419)).
**Current v4.1.6 Architecture**: Python package with slash commands
``` ```
# TypeScript Plugins (project root) # Claude Code Configuration (v4.1.6)
pm/ # PM Agent: confidence checks, orchestration .claude/
research/ # Deep Research: web search, adaptive planning ├── settings.json # User settings
index/ # Repository indexing: 94% token reduction └── commands/ # Slash commands (installed via `superclaude install`)
hooks/hooks.json # SessionStart auto-activation config ├── pm.md
├── research.md
# Claude Code Configuration └── index-repo.md
.claude/settings.json # Marketplace and plugin settings
.claude-plugin/ # Plugin manifest
├── plugin.json # Plugin metadata (3 commands: /pm, /research, /index-repo)
└── tests/ # Plugin tests
# Python Package # Python Package
src/superclaude/ # Pytest plugin + CLI tools src/superclaude/ # Pytest plugin + CLI tools
@ -40,11 +39,13 @@ src/superclaude/ # Pytest plugin + CLI tools
├── execution/ # parallel.py, reflection.py, self_correction.py ├── execution/ # parallel.py, reflection.py, self_correction.py
└── cli/ # main.py, doctor.py, install_skill.py └── cli/ # main.py, doctor.py, install_skill.py
# Command Definitions # Plugin Development (planned for v5.0 - see docs/plugin-reorg.md)
commands/ # Plugin command markdown files plugins/superclaude/ # Future plugin source (NOT ACTIVE)
├── pm.md # PM Agent command definition ├── agents/ # Agent definitions
├── research.md # Research command definition ├── commands/ # Command definitions
└── index-repo.md # Index command definition ├── hooks/ # Hook configurations
├── scripts/ # Shell scripts
└── skills/ # Skill implementations
# Project Files # Project Files
tests/ # Python test suite tests/ # Python test suite
@ -119,20 +120,21 @@ Registered via `pyproject.toml` entry point, automatically available after insta
- Automatic dependency analysis - Automatic dependency analysis
- Example: [Read files in parallel] → Analyze → [Edit files in parallel] - Example: [Read files in parallel] → Analyze → [Edit files in parallel]
### TypeScript Plugins (v2.0) ### TypeScript Plugins (Planned for v5.0)
**Location**: Plugin source lives under `plugins/superclaude/` with unified assets (agents, commands, hooks, skills). > **⚠️ NOT IMPLEMENTED**: The TypeScript plugin system described below does not exist in v4.1.6.
**Packaging**: `make build-plugin` renders `.claude-plugin/*` manifests into `dist/plugins/superclaude/`. > This is planned for v5.0. See [issue #419](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues/419) and `docs/plugin-reorg.md`.
**Distributed commands**: **Current v4.1.6 Commands** (slash commands, not plugins):
- **/sc:agent**: Session orchestrator, auto-starts via hooks - Install via: `pipx install superclaude && superclaude install`
- **/sc:index-repo**: Repository indexing + PROJECT_INDEX generation - Commands installed to: `~/.claude/commands/`
- **/sc:research**: Deep research workflow with Tavily + Context7 integration - Available commands: `/pm`, `/research`, `/index-repo` (and others)
**Editing flow**: **Planned Plugin Architecture** (v5.0 - NOT YET AVAILABLE):
- Update agents/commands/hooks/skills in `plugins/superclaude/*` - Plugin source will live under `plugins/superclaude/`
- Run `make build-plugin` locally to verify packaging - `make build-plugin` will render `.claude-plugin/*` manifests
- Optionally `make sync-plugin-repo` to push artefacts into `../SuperClaude_Plugin` - Project-local detection via `.claude-plugin/plugin.json`
- Marketplace distribution support
## 🧪 Testing with PM Agent ## 🧪 Testing with PM Agent
@ -244,49 +246,53 @@ Integrates with multiple MCP servers via **airis-mcp-gateway**.
**Usage**: TypeScript plugins and Python pytest plugin can call MCP servers. Always prefer MCP tools over speculation for documentation/research. **Usage**: TypeScript plugins and Python pytest plugin can call MCP servers. Always prefer MCP tools over speculation for documentation/research.
## 🚀 Plugin Development ## 🚀 Development & Installation
### Project-Local Plugin Detection ### Current Installation Method (v4.1.6)
This project uses **project-local plugin detection** (v2.0):
- `.claude-plugin/plugin.json` is auto-detected when you start Claude Code in this directory
- No global installation needed for development
- PM Agent auto-activates via SessionStart hook
### Plugin Architecture
```
Plugin Components:
1. Manifest templates (`plugins/superclaude/manifest/*.template.json`)
2. Command/agent assets (`plugins/superclaude/{commands,agents}/`)
3. Skills (`plugins/superclaude/skills/`)
4. Hooks & scripts (`plugins/superclaude/{hooks,scripts}/`)
```
### Development Workflow
**Standard Installation**:
```bash ```bash
# 1. Edit plugin source # Option 1: pipx (recommended)
vim plugins/superclaude/commands/agent.md pipx install superclaude
vim plugins/superclaude/skills/confidence-check/confidence.ts superclaude install
# 2. Run packaging + smoke tests # Option 2: Direct from repo
make build-plugin git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
# 3. (optional) Sync generated artefacts into ../SuperClaude_Plugin ./install.sh
make sync-plugin-repo
``` ```
### Global vs Project-Local **Development Mode**:
```bash
# Install in editable mode
make dev
**Project-Local**: # Run tests
- Work directly from `plugins/superclaude/` make test
- Use `make build-plugin` for validation / artefact refresh
- Launch Claude Code inside this repo to exercise commands hot-loaded from disk
**Distributed Package** (`../SuperClaude_Plugin`): # Verify installation
- Generated output committed for marketplace distribution make verify
- Do not edit manually—regenerate via `make sync-plugin-repo` ```
### Plugin System (Planned for v5.0 - NOT AVAILABLE)
> **⚠️ IMPORTANT**: The plugin system described in older documentation **does not exist** in v4.1.6.
> These features are planned for v5.0 (see [issue #419](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues/419)).
**What Does NOT Work** (yet):
- ❌ `.claude-plugin/` directory auto-detection
- ❌ `/plugin marketplace add` commands
- ❌ `/plugin install superclaude`
- ❌ `make build-plugin` (planned but not functional)
- ❌ Project-local plugin detection
**Future Plans** (v5.0):
- Plugin marketplace distribution
- TypeScript-based plugin architecture
- Auto-detection via `.claude-plugin/plugin.json`
- Build workflow via `make build-plugin`
See `docs/plugin-reorg.md` and `docs/next-refactor-plan.md` for implementation plans.
## 📊 Package Information ## 📊 Package Information

2
README-ja.md
View File

@ -5,7 +5,7 @@
### **Claude Codeを構造化開発プラットフォームに変換** ### **Claude Codeを構造化開発プラットフォームに変換**
<p align="center"> <p align="center">
<img src="https://img.shields.io/badge/version-4.1.5-blue" alt="Version"> <img src="https://img.shields.io/badge/version-4.1.6-blue" alt="Version">
<img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License"> <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License">
<img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"> <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome">
</p> </p>

2
README-kr.md
View File

@ -5,7 +5,7 @@
### **Claude Code를 구조화된 개발 플랫폼으로 변환** ### **Claude Code를 구조화된 개발 플랫폼으로 변환**
<p align="center"> <p align="center">
<img src="https://img.shields.io/badge/version-4.1.5-blue" alt="Version"> <img src="https://img.shields.io/badge/version-4.1.6-blue" alt="Version">
<img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License"> <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License">
<img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"> <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome">
</p> </p>

2
README-zh.md
View File

@ -5,7 +5,7 @@
### **将Claude Code转换为结构化开发平台** ### **将Claude Code转换为结构化开发平台**
<p align="center"> <p align="center">
<img src="https://img.shields.io/badge/version-4.1.5-blue" alt="Version"> <img src="https://img.shields.io/badge/version-4.1.6-blue" alt="Version">
<img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License"> <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License">
<img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"> <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome">
</p> </p>

150
README.md
View File

@ -14,7 +14,7 @@
<a href="https://github.com/SuperClaude-Org/SuperQwen_Framework" target="_blank"> <a href="https://github.com/SuperClaude-Org/SuperQwen_Framework" target="_blank">
<img src="https://img.shields.io/badge/Try-SuperQwen_Framework-orange" alt="Try SuperQwen Framework"/> <img src="https://img.shields.io/badge/Try-SuperQwen_Framework-orange" alt="Try SuperQwen Framework"/>
</a> </a>
<img src="https://img.shields.io/badge/version-4.2.0-blue" alt="Version"> <img src="https://img.shields.io/badge/version-4.1.6-blue" alt="Version">
<img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License"> <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License">
<img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"> <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome">
</p> </p>
@ -100,26 +100,44 @@ Claude Code is a product built and maintained by [Anthropic](https://www.anthrop
## ⚡ **Quick Installation** ## ⚡ **Quick Installation**
### **Project-Local Plugin (Recommended)** > **IMPORTANT**: The TypeScript plugin system described in older documentation is
> not yet available (planned for v5.0). For current installation
> instructions, please follow the steps below for v4.x.
SuperClaude v2.0+ uses **TypeScript plugins** with project-local auto-detection: ### **Current Stable Version (v4.1.6)**
SuperClaude currently uses slash commands.
**Option 1: pipx (Recommended)**
```bash ```bash
# Clone repository # Install from PyPI
pipx install superclaude
# Install commands and components
superclaude install
```
**Option 2: Direct Installation from Git**
```bash
# Clone the repository
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework cd SuperClaude_Framework
# Start Claude Code in this directory # Run the installation script
claude ./install.sh
``` ```
**That's it!** `.claude-plugin/` is auto-detected and PM Agent activates on session start. ### **Coming in v5.0 (In Development)**
**Key Features**: We are actively working on a new TypeScript plugin system (see issue [#419](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues/419) for details). When released, installation will be simplified to:
- ✅ **Zero Install**: No copying, no configuration
- ✅ **Hot Reload**: Edit TypeScript → Save → Instant reflection ```bash
- ✅ **Auto-Activation**: PM Agent starts automatically (SessionStart hook) # This feature is not yet available
- ✅ **Safe Development**: Separate sandbox from global Claude Code /plugin marketplace add SuperClaude-Org/superclaude-plugin-marketplace
/plugin install superclaude
```
**Status**: In development. No ETA has been set.
### **Enhanced Performance (Optional MCPs)** ### **Enhanced Performance (Optional MCPs)**
@ -145,69 +163,6 @@ For **2-3x faster** execution and **30-50% fewer tokens**, optionally install MC
</div> </div>
<details>
<summary><b>⚠️ IMPORTANT: Upgrading from SuperClaude V1.x (Slash Commands)</b></summary>
**V2.0 introduces breaking changes - migration from slash commands to TypeScript plugins:**
```bash
# 1. Remove old slash commands (if installed)
rm -rf ~/.claude/commands/sc/
# 2. Use new plugin (project-local)
cd SuperClaude_Framework
claude # .claude-plugin/ auto-detected
```
**What's New in V2.0:**
- ✅ TypeScript plugins (hot reload support)
- ✅ Project-local detection (zero install)
- ✅ Auto-activation via SessionStart hook
- ✅ 3 core plugins: PM Agent, Research, Index
- ✅ Confidence-driven workflow (≥90% threshold, Precision/Recall 1.0)
**Migration Notes:**
- Old: `/sc:pm`, `/sc:research`, `/sc:index-repo` (27 commands)
- New: `/pm`, `/research`, `/index-repo` (3 plugin commands)
- Installation: Global `~/.claude/commands/` → Project-local `.claude-plugin/`
- Just `cd` to project directory and run `claude`
</details>
<details>
<summary><b>💡 Troubleshooting</b></summary>
**Plugin not loading?**
```bash
# Verify you're in the project directory
pwd # Should show: /path/to/SuperClaude_Framework
# Check .claude-plugin/ exists
ls .claude-plugin/plugin.json
# Restart Claude Code in this directory
claude
```
**Commands not working (/pm, /research, /index-repo)?**
- Ensure you started `claude` from the SuperClaude_Framework directory
- Check for errors in Claude Code output
- Verify `.claude-plugin/plugin.json` has correct structure
**Hot reload not working?**
- Edit `.claude-plugin/pm/index.ts`
- Save file
- Changes should reflect immediately (no restart needed)
**Development mode (for contributors):**
```bash
# Install Python package for testing
make install
make verify
uv run pytest
```
</details>
--- ---
<div align="center"> <div align="center">
@ -270,9 +225,9 @@ uv run pytest
<div align="center"> <div align="center">
## 🎉 **What's New in V2.0** ## 🎉 **What's New in v4.1**
> *Version 2.0 brings architectural transformation: migration from 27 slash commands to 3 TypeScript plugins with hot reload and auto-activation.* > *Version 4.1 focuses on stabilizing the slash command architecture, enhancing agent capabilities, and improving documentation.*
<table> <table>
<tr> <tr>
@ -290,13 +245,12 @@ uv run pytest
</td> </td>
<td width="50%"> <td width="50%">
### 🔥 **TypeScript Plugins** ### ⚡ **Optimized Performance**
**3 core plugins** with hot reload: **Smaller framework, bigger projects:**
- **PM Agent**: Confidence-driven orchestration (≥90% threshold) - Reduced framework footprint
- **Research**: Deep web search with adaptive planning - More context for your code
- **Index**: 94% token reduction (58K → 3K) - Longer conversations possible
- Auto-activation via SessionStart hook - Complex operations enabled
- Edit → Save → Instant reflection (no restart)
</td> </td>
</tr> </tr>
@ -332,16 +286,6 @@ uv run pytest
<tr> <tr>
<td width="50%"> <td width="50%">
### ⚡ **Optimized Performance**
**Smaller framework, bigger projects:**
- Reduced framework footprint
- More context for your code
- Longer conversations possible
- Complex operations enabled
</td>
<td width="50%">
### 📚 **Documentation Overhaul** ### 📚 **Documentation Overhaul**
**Complete rewrite** for developers: **Complete rewrite** for developers:
- Real examples & use cases - Real examples & use cases
@ -349,6 +293,16 @@ uv run pytest
- Practical workflows included - Practical workflows included
- Better navigation structure - Better navigation structure
</td>
<td width="50%">
### 🧪 **Enhanced Stability**
**Focus on reliability:**
- Bug fixes for core commands
- Improved test coverage
- More robust error handling
- CI/CD pipeline improvements
</td> </td>
</tr> </tr>
</table> </table>
@ -474,11 +428,11 @@ The Deep Research system intelligently coordinates multiple tools:
</td> </td>
<td valign="top"> <td valign="top">
- 🎯 [**Plugin Commands**](docs/user-guide/commands.md) - 🎯 [**Slash Commands**](docs/user-guide/commands.md)
*3 core plugin commands* *Full list of `/sc` commands*
- 🤖 [**Agents Guide**](docs/user-guide/agents.md) - 🤖 [**Agents Guide**](docs/user-guide/agents.md)
*15 specialized agents* *16 specialized agents*
- 🎨 [**Behavioral Modes**](docs/user-guide/modes.md) - 🎨 [**Behavioral Modes**](docs/user-guide/modes.md)
*7 adaptive modes* *7 adaptive modes*
@ -487,7 +441,7 @@ The Deep Research system intelligently coordinates multiple tools:
*Control behaviors* *Control behaviors*
- 🔧 [**MCP Servers**](docs/user-guide/mcp-servers.md) - 🔧 [**MCP Servers**](docs/user-guide/mcp-servers.md)
*7 server integrations* *8 server integrations*
- 💼 [**Session Management**](docs/user-guide/session-management.md) - 💼 [**Session Management**](docs/user-guide/session-management.md)
*Save & restore state* *Save & restore state*