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
**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)
pm/ # PM Agent: confidence checks, orchestration
research/ # Deep Research: web search, adaptive planning
index/ # Repository indexing: 94% token reduction
hooks/hooks.json # SessionStart auto-activation config
# Claude Code Configuration
.claude/settings.json # Marketplace and plugin settings
.claude-plugin/ # Plugin manifest
├── plugin.json # Plugin metadata (3 commands: /pm, /research, /index-repo)
└── tests/ # Plugin tests
# Claude Code Configuration (v4.1.6)
.claude/
├── settings.json # User settings
└── commands/ # Slash commands (installed via `superclaude install`)
├── pm.md
├── research.md
└── index-repo.md
# Python Package
src/superclaude/ # Pytest plugin + CLI tools
@ -40,11 +39,13 @@ src/superclaude/ # Pytest plugin + CLI tools
├── execution/ # parallel.py, reflection.py, self_correction.py
└── cli/ # main.py, doctor.py, install_skill.py
# Command Definitions
commands/ # Plugin command markdown files
├── pm.md # PM Agent command definition
├── research.md # Research command definition
└── index-repo.md # Index command definition
# Plugin Development (planned for v5.0 - see docs/plugin-reorg.md)
plugins/superclaude/ # Future plugin source (NOT ACTIVE)
├── agents/ # Agent definitions
├── commands/ # Command definitions
├── hooks/ # Hook configurations
├── scripts/ # Shell scripts
└── skills/ # Skill implementations
# Project Files
tests/ # Python test suite
@ -119,20 +120,21 @@ Registered via `pyproject.toml` entry point, automatically available after insta
- Automatic dependency analysis
- 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).
**Packaging**: `make build-plugin` renders `.claude-plugin/*` manifests into `dist/plugins/superclaude/`.
> **⚠️ NOT IMPLEMENTED**: The TypeScript plugin system described below does not exist in v4.1.6.
> 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**:
- **/sc:agent**: Session orchestrator, auto-starts via hooks
- **/sc:index-repo**: Repository indexing + PROJECT_INDEX generation
- **/sc:research**: Deep research workflow with Tavily + Context7 integration
**Current v4.1.6 Commands** (slash commands, not plugins):
- Install via: `pipx install superclaude && superclaude install`
- Commands installed to: `~/.claude/commands/`
- Available commands: `/pm`, `/research`, `/index-repo` (and others)
**Editing flow**:
- Update agents/commands/hooks/skills in `plugins/superclaude/*`
- Run `make build-plugin` locally to verify packaging
- Optionally `make sync-plugin-repo` to push artefacts into `../SuperClaude_Plugin`
**Planned Plugin Architecture** (v5.0 - NOT YET AVAILABLE):
- Plugin source will live under `plugins/superclaude/`
- `make build-plugin` will render `.claude-plugin/*` manifests
- Project-local detection via `.claude-plugin/plugin.json`
- Marketplace distribution support
## 🧪 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.
## 🚀 Plugin Development
## 🚀 Development & Installation
### Project-Local Plugin Detection
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
### Current Installation Method (v4.1.6)
**Standard Installation**:
```bash
# 1. Edit plugin source
vim plugins/superclaude/commands/agent.md
vim plugins/superclaude/skills/confidence-check/confidence.ts
# Option 1: pipx (recommended)
pipx install superclaude
superclaude install
# 2. Run packaging + smoke tests
make build-plugin
# 3. (optional) Sync generated artefacts into ../SuperClaude_Plugin
make sync-plugin-repo
# Option 2: Direct from repo
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
./install.sh
```
### Global vs Project-Local
**Development Mode**:
```bash
# Install in editable mode
make dev
**Project-Local**:
- Work directly from `plugins/superclaude/`
- Use `make build-plugin` for validation / artefact refresh
- Launch Claude Code inside this repo to exercise commands hot-loaded from disk
# Run tests
make test
**Distributed Package** (`../SuperClaude_Plugin`):
- Generated output committed for marketplace distribution
- Do not edit manually—regenerate via `make sync-plugin-repo`
# Verify installation
make verify
```
### 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

2
README-ja.md
View File

@ -5,7 +5,7 @@
### **Claude Codeを構造化開発プラットフォームに変換**
<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/PRs-welcome-brightgreen.svg" alt="PRs Welcome">
</p>

2
README-kr.md
View File

@ -5,7 +5,7 @@
### **Claude Code를 구조화된 개발 플랫폼으로 변환**
<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/PRs-welcome-brightgreen.svg" alt="PRs Welcome">
</p>

2
README-zh.md
View File

@ -5,7 +5,7 @@
### **将Claude Code转换为结构化开发平台**
<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/PRs-welcome-brightgreen.svg" alt="PRs Welcome">
</p>

150
README.md
View File

@ -14,7 +14,7 @@
<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"/>
</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/PRs-welcome-brightgreen.svg" alt="PRs Welcome">
</p>
@ -100,26 +100,44 @@ Claude Code is a product built and maintained by [Anthropic](https://www.anthrop
## ⚡ **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
# 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
cd SuperClaude_Framework
# Start Claude Code in this directory
claude
# Run the installation script
./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**:
- ✅ **Zero Install**: No copying, no configuration
- ✅ **Hot Reload**: Edit TypeScript → Save → Instant reflection
- ✅ **Auto-Activation**: PM Agent starts automatically (SessionStart hook)
- ✅ **Safe Development**: Separate sandbox from global Claude Code
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:
```bash
# This feature is not yet available
/plugin marketplace add SuperClaude-Org/superclaude-plugin-marketplace
/plugin install superclaude
```
**Status**: In development. No ETA has been set.
### **Enhanced Performance (Optional MCPs)**
@ -145,69 +163,6 @@ For **2-3x faster** execution and **30-50% fewer tokens**, optionally install MC
</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">
@ -270,9 +225,9 @@ uv run pytest
<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>
<tr>
@ -290,13 +245,12 @@ uv run pytest
</td>
<td width="50%">
### 🔥 **TypeScript Plugins**
**3 core plugins** with hot reload:
- **PM Agent**: Confidence-driven orchestration (≥90% threshold)
- **Research**: Deep web search with adaptive planning
- **Index**: 94% token reduction (58K → 3K)
- Auto-activation via SessionStart hook
- Edit → Save → Instant reflection (no restart)
### ⚡ **Optimized Performance**
**Smaller framework, bigger projects:**
- Reduced framework footprint
- More context for your code
- Longer conversations possible
- Complex operations enabled
</td>
</tr>
@ -332,16 +286,6 @@ uv run pytest
<tr>
<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**
**Complete rewrite** for developers:
- Real examples & use cases
@ -349,6 +293,16 @@ uv run pytest
- Practical workflows included
- 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>
</tr>
</table>
@ -474,11 +428,11 @@ The Deep Research system intelligently coordinates multiple tools:
</td>
<td valign="top">
- 🎯 [**Plugin Commands**](docs/user-guide/commands.md)
*3 core plugin commands*
- 🎯 [**Slash Commands**](docs/user-guide/commands.md)
*Full list of `/sc` commands*
- 🤖 [**Agents Guide**](docs/user-guide/agents.md)
*15 specialized agents*
*16 specialized agents*
- 🎨 [**Behavioral Modes**](docs/user-guide/modes.md)
*7 adaptive modes*
@ -487,7 +441,7 @@ The Deep Research system intelligently coordinates multiple tools:
*Control behaviors*
- 🔧 [**MCP Servers**](docs/user-guide/mcp-servers.md)
*7 server integrations*
*8 server integrations*
- 💼 [**Session Management**](docs/user-guide/session-management.md)
*Save & restore state*