mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
refactor: migrate plugin structure from .claude-plugin to project root
Restructure plugin to follow Claude Code official documentation: - Move TypeScript files from .claude-plugin/* to project root - Create Markdown command files in commands/ - Update plugin.json to reference ./commands/*.md - Add comprehensive plugin installation guide Changes: - Commands: pm.md, research.md, index-repo.md (new Markdown format) - TypeScript: pm/, research/, index/ moved to root - Hooks: hooks/hooks.json moved to root - Documentation: PLUGIN_INSTALL.md, updated CLAUDE.md, Makefile Note: This commit represents transition state. Original TypeScript-based execution system was replaced with Markdown commands. Further redesign needed to properly integrate Skills and Hooks per official docs. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
kazuki
@@ -1,12 +1,15 @@
|
|||||||
{
|
{
|
||||||
"name": "superclaude-local",
|
"name": "superclaude-local",
|
||||||
"description": "Local development marketplace for SuperClaude plugins",
|
"description": "Local development marketplace for SuperClaude plugins",
|
||||||
|
"owner": {
|
||||||
|
"name": "SuperClaude Team"
|
||||||
|
},
|
||||||
"plugins": [
|
"plugins": [
|
||||||
{
|
{
|
||||||
"name": "pm-agent",
|
"name": "pm-agent",
|
||||||
"path": ".",
|
"source": "./pm-agent",
|
||||||
"version": "1.0.0",
|
"version": "2.1.0",
|
||||||
"description": "Project Manager Agent with 90% confidence checks and zero-footprint memory"
|
"description": "PM Agent - Confidence-driven orchestrator with deep research and repository indexing"
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1,38 +1,18 @@
|
|||||||
{
|
{
|
||||||
"name": "pm-agent",
|
"name": "pm-agent",
|
||||||
"version": "2.0.0",
|
"version": "2.1.0",
|
||||||
"description": "PM Agent - Auto-activating orchestrator with hot reload support",
|
"description": "PM Agent - Confidence-driven orchestrator with deep research and repository indexing",
|
||||||
"author": "SuperClaude Team",
|
"author": {
|
||||||
"main": "pm/index.ts",
|
"name": "SuperClaude Team"
|
||||||
"commands": [
|
|
||||||
{
|
|
||||||
"name": "pm",
|
|
||||||
"path": "pm/index.ts",
|
|
||||||
"description": "Activate PM Agent with confidence-driven workflow (auto-starts via hooks)"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"name": "research",
|
|
||||||
"path": "research/index.ts",
|
|
||||||
"description": "Deep web research with adaptive planning and intelligent search"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"name": "index-repo",
|
|
||||||
"path": "index/index.ts",
|
|
||||||
"description": "Create repository structure index for fast context loading (94% token reduction)"
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"skills": [
|
|
||||||
{
|
|
||||||
"name": "confidence_check",
|
|
||||||
"path": "pm/confidence.ts",
|
|
||||||
"description": "Pre-implementation confidence assessment (≥90% required, Precision/Recall 1.0)"
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"hooks": {
|
|
||||||
"path": "hooks/hooks.json",
|
|
||||||
"description": "SessionStart auto-activation: /pm runs automatically on session start"
|
|
||||||
},
|
},
|
||||||
"engines": {
|
"homepage": "https://github.com/kazukixjp/superclaude",
|
||||||
"node": ">=18.0.0"
|
"repository": "https://github.com/kazukixjp/superclaude",
|
||||||
}
|
"license": "MIT",
|
||||||
|
"keywords": ["pm-agent", "confidence-check", "research", "indexing"],
|
||||||
|
"commands": [
|
||||||
|
"./commands/pm.md",
|
||||||
|
"./commands/research.md",
|
||||||
|
"./commands/index-repo.md"
|
||||||
|
],
|
||||||
|
"hooks": "./hooks/hooks.json"
|
||||||
}
|
}
|
||||||
|
|||||||
426
CLAUDE.md
426
CLAUDE.md
@@ -4,381 +4,229 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
|||||||
|
|
||||||
## 🐍 Python Environment Rules
|
## 🐍 Python Environment Rules
|
||||||
|
|
||||||
**CRITICAL**: This project uses **UV** for all Python operations.
|
**CRITICAL**: This project uses **UV** for all Python operations. Never use `python -m`, `pip install`, or `python script.py` directly.
|
||||||
|
|
||||||
### Required Commands
|
### Required Commands
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# ❌ WRONG - Never use these
|
# All Python operations must use UV
|
||||||
python -m pytest
|
uv run pytest # Run tests
|
||||||
pip install package
|
uv run pytest tests/pm_agent/ # Run specific tests
|
||||||
python script.py
|
uv pip install package # Install dependencies
|
||||||
|
uv run python script.py # Execute scripts
|
||||||
# ✅ CORRECT - Always use UV
|
|
||||||
uv run pytest
|
|
||||||
uv pip install package
|
|
||||||
uv run python script.py
|
|
||||||
```
|
|
||||||
|
|
||||||
### Why UV?
|
|
||||||
|
|
||||||
- **Fast**: 10-100x faster than pip
|
|
||||||
- **Reliable**: Lock file ensures reproducibility
|
|
||||||
- **Clean**: No system Python pollution
|
|
||||||
- **Standard**: Project convention for consistency
|
|
||||||
|
|
||||||
### Common Operations
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Run tests
|
|
||||||
uv run pytest tests/ -v
|
|
||||||
|
|
||||||
# Install dependencies
|
|
||||||
uv pip install -r requirements.txt
|
|
||||||
|
|
||||||
# Run specific script
|
|
||||||
uv run python scripts/analyze_workflow_metrics.py
|
|
||||||
|
|
||||||
# Create virtual environment (if needed)
|
|
||||||
uv venv
|
|
||||||
```
|
|
||||||
|
|
||||||
### Integration with Docker
|
|
||||||
|
|
||||||
When using Docker for development:
|
|
||||||
```bash
|
|
||||||
# Inside Docker container
|
|
||||||
docker compose exec workspace uv run pytest
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 📂 Project Structure
|
## 📂 Project Structure
|
||||||
|
|
||||||
```
|
**Dual-language architecture**: TypeScript plugins for Claude Code integration + Python package for testing/CLI tools.
|
||||||
SuperClaude_Framework/
|
|
||||||
├── .claude-plugin/ # TypeScript plugins (v2.0 architecture)
|
|
||||||
│ ├── pm/ # PM Agent plugin
|
|
||||||
│ │ ├── index.ts # Main orchestrator (SessionStart auto-activation)
|
|
||||||
│ │ ├── confidence.ts # Confidence assessment (≥90% threshold, Precision/Recall 1.0)
|
|
||||||
│ │ └── package.json # Dependencies
|
|
||||||
│ ├── research/ # Deep Research plugin
|
|
||||||
│ │ ├── index.ts # Web research with adaptive planning
|
|
||||||
│ │ └── package.json # Dependencies
|
|
||||||
│ ├── index/ # Repository indexing plugin
|
|
||||||
│ │ ├── index.ts # 94% token reduction (58K → 3K)
|
|
||||||
│ │ └── package.json # Dependencies
|
|
||||||
│ ├── hooks/
|
|
||||||
│ │ └── hooks.json # SessionStart hook configuration
|
|
||||||
│ ├── tests/ # Plugin tests (confidence_check, test cases)
|
|
||||||
│ └── plugin.json # Plugin manifest (v2.0.0)
|
|
||||||
├── src/superclaude/ # Python package (pytest plugin, CLI)
|
|
||||||
│ ├── __init__.py # Exports: ConfidenceChecker, SelfCheckProtocol, ReflexionPattern
|
|
||||||
│ ├── pytest_plugin.py # Auto-loaded pytest integration
|
|
||||||
│ ├── pm_agent/ # PM Agent core (confidence, self-check, reflexion)
|
|
||||||
│ ├── cli/ # CLI commands (main, doctor, install_skill)
|
|
||||||
│ └── execution/ # Execution patterns (parallel, reflection, self_correction)
|
|
||||||
├── docs/ # Documentation
|
|
||||||
├── scripts/ # Analysis tools (A/B testing, workflow metrics)
|
|
||||||
└── tests/ # Python test suite
|
|
||||||
```
|
|
||||||
|
|
||||||
**Architecture Overview:**
|
```
|
||||||
- **TypeScript Plugins** (.claude-plugin/): Hot reload, auto-activation, production workflows
|
# TypeScript Plugins (project root)
|
||||||
- **Python Package** (src/superclaude/): pytest plugin, CLI tools, PM Agent core logic
|
pm/ # PM Agent: confidence checks, orchestration
|
||||||
- **Dual Language**: TypeScript for Claude Code integration, Python for testing/tooling
|
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
|
||||||
|
|
||||||
|
# Python Package
|
||||||
|
src/superclaude/ # Pytest plugin + CLI tools
|
||||||
|
├── pytest_plugin.py # Auto-loaded pytest integration
|
||||||
|
├── pm_agent/ # confidence.py, self_check.py, reflexion.py
|
||||||
|
├── execution/ # parallel.py, reflection.py, self_correction.py
|
||||||
|
└── cli/ # main.py, doctor.py, install_skill.py
|
||||||
|
|
||||||
|
# Project Files
|
||||||
|
tests/ # Python test suite
|
||||||
|
docs/ # Documentation
|
||||||
|
scripts/ # Analysis tools (workflow metrics, A/B testing)
|
||||||
|
PLANNING.md # Architecture, absolute rules
|
||||||
|
TASK.md # Current tasks
|
||||||
|
KNOWLEDGE.md # Accumulated insights
|
||||||
|
```
|
||||||
|
|
||||||
## 🔧 Development Workflow
|
## 🔧 Development Workflow
|
||||||
|
|
||||||
### Makefile Commands (Recommended)
|
### Essential Commands
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Development setup
|
# Setup
|
||||||
make dev # Install in editable mode with [dev] dependencies (RECOMMENDED)
|
make dev # Install in editable mode with dev dependencies
|
||||||
make verify # Verify installation health (package, version, plugin, doctor)
|
make verify # Verify installation (package, plugin, health)
|
||||||
|
|
||||||
# Testing
|
# Testing
|
||||||
make test # Run full test suite with pytest
|
make test # Run full test suite
|
||||||
make test-plugin # Verify pytest plugin auto-discovery
|
uv run pytest tests/pm_agent/ -v # Run specific directory
|
||||||
|
uv run pytest tests/test_file.py -v # Run specific file
|
||||||
|
uv run pytest -m confidence_check # Run by marker
|
||||||
|
uv run pytest --cov=superclaude # With coverage
|
||||||
|
|
||||||
# Code quality
|
# Code Quality
|
||||||
make lint # Run ruff linter
|
make lint # Run ruff linter
|
||||||
make format # Format code with ruff
|
make format # Format code with ruff
|
||||||
|
make doctor # Health check diagnostics
|
||||||
|
|
||||||
# Maintenance
|
# Maintenance
|
||||||
make doctor # Run health check diagnostics
|
make clean # Remove build artifacts
|
||||||
make clean # Remove build artifacts and caches
|
|
||||||
make translate # Translate README to zh/ja (requires neural-cli)
|
|
||||||
```
|
|
||||||
|
|
||||||
### Running Tests Directly
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# All tests
|
|
||||||
uv run pytest
|
|
||||||
|
|
||||||
# Specific test file
|
|
||||||
uv run pytest tests/pm_agent/test_confidence_check.py -v
|
|
||||||
|
|
||||||
# By directory
|
|
||||||
uv run pytest tests/pm_agent/ -v
|
|
||||||
|
|
||||||
# By marker
|
|
||||||
uv run pytest -m confidence_check
|
|
||||||
uv run pytest -m "unit and not integration"
|
|
||||||
|
|
||||||
# With coverage
|
|
||||||
uv run pytest --cov=superclaude --cov-report=html
|
|
||||||
```
|
|
||||||
|
|
||||||
### Code Quality
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Linting
|
|
||||||
uv run ruff check .
|
|
||||||
|
|
||||||
# Formatting
|
|
||||||
uv run ruff format .
|
|
||||||
|
|
||||||
# Type checking (if configured)
|
|
||||||
uv run mypy superclaude/
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 📦 Core Architecture
|
## 📦 Core Architecture
|
||||||
|
|
||||||
### Pytest Plugin System (Auto-loaded)
|
### Pytest Plugin (Auto-loaded)
|
||||||
|
|
||||||
SuperClaude includes an **auto-loaded pytest plugin** registered via entry points in pyproject.toml:66-67:
|
Registered via `pyproject.toml` entry point, automatically available after installation.
|
||||||
|
|
||||||
```toml
|
**Fixtures**: `confidence_checker`, `self_check_protocol`, `reflexion_pattern`, `token_budget`, `pm_context`
|
||||||
[project.entry-points.pytest11]
|
|
||||||
superclaude = "superclaude.pytest_plugin"
|
|
||||||
```
|
|
||||||
|
|
||||||
**Provides:**
|
**Auto-markers**:
|
||||||
- Custom fixtures: `confidence_checker`, `self_check_protocol`, `reflexion_pattern`, `token_budget`, `pm_context`
|
- Tests in `/unit/` → `@pytest.mark.unit`
|
||||||
- Auto-markers: Tests in `/unit/` → `@pytest.mark.unit`, `/integration/` → `@pytest.mark.integration`
|
- Tests in `/integration/` → `@pytest.mark.integration`
|
||||||
- Custom markers: `@pytest.mark.confidence_check`, `@pytest.mark.self_check`, `@pytest.mark.reflexion`
|
|
||||||
- PM Agent integration for test lifecycle hooks
|
**Custom markers**: `@pytest.mark.confidence_check`, `@pytest.mark.self_check`, `@pytest.mark.reflexion`
|
||||||
|
|
||||||
### PM Agent - Three Core Patterns
|
### PM Agent - Three Core Patterns
|
||||||
|
|
||||||
Located in `src/superclaude/pm_agent/`:
|
**1. ConfidenceChecker** (src/superclaude/pm_agent/confidence.py)
|
||||||
|
- Pre-execution confidence assessment: ≥90% required, 70-89% present alternatives, <70% ask questions
|
||||||
|
- Prevents wrong-direction work, ROI: 25-250x token savings
|
||||||
|
|
||||||
**1. ConfidenceChecker (Pre-execution)**
|
**2. SelfCheckProtocol** (src/superclaude/pm_agent/self_check.py)
|
||||||
- Prevents wrong-direction execution by assessing confidence BEFORE starting
|
- Post-implementation evidence-based validation
|
||||||
- Token budget: 100-200 tokens
|
- No speculation - verify with tests/docs
|
||||||
- ROI: 25-250x token savings when stopping wrong implementations
|
|
||||||
- Confidence levels:
|
|
||||||
- High (≥90%): Proceed immediately
|
|
||||||
- Medium (70-89%): Present alternatives
|
|
||||||
- Low (<70%): STOP → Ask specific questions
|
|
||||||
|
|
||||||
**2. SelfCheckProtocol (Post-implementation)**
|
**3. ReflexionPattern** (src/superclaude/pm_agent/reflexion.py)
|
||||||
- Evidence-based validation after implementation
|
- Error learning and prevention
|
||||||
- No speculation allowed - verify with actual tests/docs
|
- Cross-session pattern matching
|
||||||
- Ensures implementation matches requirements
|
|
||||||
|
|
||||||
**3. ReflexionPattern (Error learning)**
|
### Parallel Execution
|
||||||
- Records failures for future prevention
|
|
||||||
- Pattern matching for similar errors
|
|
||||||
- Cross-session learning and improvement
|
|
||||||
|
|
||||||
### Module Structure
|
**Wave → Checkpoint → Wave pattern** (src/superclaude/execution/parallel.py):
|
||||||
|
- 3.5x faster than sequential execution
|
||||||
|
- Automatic dependency analysis
|
||||||
|
- Example: [Read files in parallel] → Analyze → [Edit files in parallel]
|
||||||
|
|
||||||
```
|
### TypeScript Plugins (v2.0)
|
||||||
src/superclaude/
|
|
||||||
├── __init__.py # Exports: ConfidenceChecker, SelfCheckProtocol, ReflexionPattern
|
|
||||||
├── pytest_plugin.py # Auto-loaded pytest integration (fixtures, hooks, markers)
|
|
||||||
├── pm_agent/ # PM Agent core (confidence, self-check, reflexion)
|
|
||||||
├── cli/ # CLI commands (main, doctor, install_skill)
|
|
||||||
└── execution/ # Execution patterns (parallel, reflection, self_correction)
|
|
||||||
```
|
|
||||||
|
|
||||||
### Parallel Execution Engine
|
**Location**: Plugin source files are at **project root** (pm/, research/, index/), not in .claude-plugin/.
|
||||||
|
**Hot reload enabled** - edit .ts file, save, instant reflection (no restart).
|
||||||
|
|
||||||
Located in `src/superclaude/execution/parallel.py`:
|
**Three plugins**:
|
||||||
|
- **/pm**: Auto-starts on session (hooks/hooks.json), confidence-driven orchestration
|
||||||
|
- **/research**: Deep web research, adaptive planning, Tavily MCP integration
|
||||||
|
- **/index-repo**: Repository indexing, 94% token reduction (58K → 3K)
|
||||||
|
|
||||||
- **Automatic parallelization**: Analyzes task dependencies and executes independent operations concurrently
|
**Important**: When editing plugins, modify files in pm/, research/, or index/ at project root, not in .claude-plugin/.
|
||||||
- **Wave → Checkpoint → Wave pattern**: 3.5x faster than sequential execution
|
|
||||||
- **Dependency graph**: Topological sort for optimal grouping
|
|
||||||
- **ThreadPoolExecutor**: Concurrent execution with result aggregation
|
|
||||||
|
|
||||||
Example pattern:
|
## 🧪 Testing with PM Agent
|
||||||
```python
|
|
||||||
# Wave 1: Read files in parallel
|
|
||||||
tasks = [read_file1, read_file2, read_file3]
|
|
||||||
|
|
||||||
# Checkpoint: Analyze results
|
### Example Test with Markers
|
||||||
|
|
||||||
# Wave 2: Edit files in parallel based on analysis
|
|
||||||
tasks = [edit_file1, edit_file2, edit_file3]
|
|
||||||
```
|
|
||||||
|
|
||||||
### Plugin Architecture (v2.0)
|
|
||||||
|
|
||||||
**TypeScript Plugins** (.claude-plugin/):
|
|
||||||
- **pm/index.ts**: PM Agent orchestrator with SessionStart auto-activation
|
|
||||||
- Confidence-driven workflow (≥90% threshold required)
|
|
||||||
- Git status detection & display
|
|
||||||
- Auto-starts on every session (no user command needed)
|
|
||||||
- **research/index.ts**: Deep web research with adaptive planning
|
|
||||||
- 3 strategies: Planning-Only, Intent-Planning, Unified
|
|
||||||
- Multi-hop reasoning (up to 5 iterations)
|
|
||||||
- Tavily MCP integration
|
|
||||||
- **index/index.ts**: Repository indexing for token efficiency
|
|
||||||
- 94% token reduction (58K → 3K tokens)
|
|
||||||
- Parallel analysis (5 concurrent tasks)
|
|
||||||
- PROJECT_INDEX.md generation
|
|
||||||
|
|
||||||
**Hot Reload**:
|
|
||||||
- Edit TypeScript file → Save → Instant reflection (no restart)
|
|
||||||
- Faster iteration than Markdown commands
|
|
||||||
|
|
||||||
**SessionStart Hook**:
|
|
||||||
- Configured in hooks/hooks.json
|
|
||||||
- Auto-executes /pm command on session start
|
|
||||||
- User sees PM Agent activation message automatically
|
|
||||||
|
|
||||||
## 🧪 Testing with PM Agent Markers
|
|
||||||
|
|
||||||
### Custom Pytest Markers
|
|
||||||
|
|
||||||
```python
|
```python
|
||||||
# Pre-execution confidence check (skips if confidence < 70%)
|
|
||||||
@pytest.mark.confidence_check
|
@pytest.mark.confidence_check
|
||||||
def test_feature(confidence_checker):
|
def test_feature(confidence_checker):
|
||||||
|
"""Pre-execution confidence check - skips if < 70%"""
|
||||||
context = {"test_name": "test_feature", "has_official_docs": True}
|
context = {"test_name": "test_feature", "has_official_docs": True}
|
||||||
assert confidence_checker.assess(context) >= 0.7
|
assert confidence_checker.assess(context) >= 0.7
|
||||||
|
|
||||||
# Post-implementation validation with evidence requirement
|
|
||||||
@pytest.mark.self_check
|
@pytest.mark.self_check
|
||||||
def test_implementation(self_check_protocol):
|
def test_implementation(self_check_protocol):
|
||||||
|
"""Post-implementation validation with evidence"""
|
||||||
implementation = {"code": "...", "tests": [...]}
|
implementation = {"code": "...", "tests": [...]}
|
||||||
passed, issues = self_check_protocol.validate(implementation)
|
passed, issues = self_check_protocol.validate(implementation)
|
||||||
assert passed, f"Validation failed: {issues}"
|
assert passed, f"Validation failed: {issues}"
|
||||||
|
|
||||||
# Error learning and prevention
|
|
||||||
@pytest.mark.reflexion
|
@pytest.mark.reflexion
|
||||||
def test_error_prone_feature(reflexion_pattern):
|
def test_error_learning(reflexion_pattern):
|
||||||
# If this test fails, reflexion records the error for future prevention
|
"""If test fails, reflexion records for future prevention"""
|
||||||
pass
|
pass
|
||||||
|
|
||||||
# Token budget allocation (simple: 200, medium: 1000, complex: 2500)
|
@pytest.mark.complexity("medium") # simple: 200, medium: 1000, complex: 2500
|
||||||
@pytest.mark.complexity("medium")
|
|
||||||
def test_with_budget(token_budget):
|
def test_with_budget(token_budget):
|
||||||
|
"""Token budget allocation"""
|
||||||
assert token_budget.limit == 1000
|
assert token_budget.limit == 1000
|
||||||
```
|
```
|
||||||
|
|
||||||
### Available Fixtures
|
|
||||||
|
|
||||||
From `src/superclaude/pytest_plugin.py`:
|
|
||||||
|
|
||||||
- `confidence_checker` - Pre-execution confidence assessment
|
|
||||||
- `self_check_protocol` - Post-implementation validation
|
|
||||||
- `reflexion_pattern` - Error learning pattern
|
|
||||||
- `token_budget` - Token allocation management
|
|
||||||
- `pm_context` - PM Agent context (memory directory structure)
|
|
||||||
|
|
||||||
## 🌿 Git Workflow
|
## 🌿 Git Workflow
|
||||||
|
|
||||||
### Branch Strategy
|
**Branch structure**: `master` (production) ← `integration` (testing) ← `feature/*`, `fix/*`, `docs/*`
|
||||||
|
|
||||||
```
|
**Standard workflow**:
|
||||||
master # Production-ready releases
|
1. Create branch from `integration`: `git checkout -b feature/your-feature`
|
||||||
├── integration # Integration testing branch (current)
|
|
||||||
├── feature/* # Feature development
|
|
||||||
├── fix/* # Bug fixes
|
|
||||||
└── docs/* # Documentation updates
|
|
||||||
```
|
|
||||||
|
|
||||||
**Workflow:**
|
|
||||||
1. Create feature branch from `integration`: `git checkout -b feature/your-feature`
|
|
||||||
2. Develop with tests: `uv run pytest`
|
2. Develop with tests: `uv run pytest`
|
||||||
3. Commit with conventional commits: `git commit -m "feat: description"`
|
3. Commit: `git commit -m "feat: description"` (conventional commits)
|
||||||
4. Merge to `integration` for integration testing
|
4. Merge to `integration` → validate → merge to `master`
|
||||||
5. After validation: `integration` → `master`
|
|
||||||
|
|
||||||
**Current branch:** `integration` (see gitStatus above)
|
**Current branch**: See git status in session start output
|
||||||
|
|
||||||
## 🚀 Contributing
|
### Parallel Development with Git Worktrees
|
||||||
|
|
||||||
When making changes:
|
**CRITICAL**: When running multiple Claude Code sessions in parallel, use `git worktree` to avoid conflicts.
|
||||||
|
|
||||||
1. Create feature branch from `integration`
|
```bash
|
||||||
2. Make changes with tests (maintain coverage)
|
# Create worktree for integration branch
|
||||||
3. Commit with conventional commits (feat:, fix:, docs:, refactor:, test:)
|
cd ~/github/superclaude
|
||||||
4. Merge to `integration` for integration testing
|
git worktree add ../superclaude-integration integration
|
||||||
5. Small, reviewable PRs preferred
|
|
||||||
|
|
||||||
## 📝 Essential Documentation
|
# Create worktree for feature branch
|
||||||
|
git worktree add ../superclaude-feature feature/pm-agent
|
||||||
|
```
|
||||||
|
|
||||||
**Read these files IN ORDER at session start:**
|
**Benefits**:
|
||||||
|
- Run Claude Code sessions on different branches simultaneously
|
||||||
|
- No branch switching conflicts
|
||||||
|
- Independent working directories
|
||||||
|
- Parallel development without state corruption
|
||||||
|
|
||||||
1. **PLANNING.md** - Architecture, design principles, absolute rules
|
**Usage**:
|
||||||
2. **TASK.md** - Current tasks and priorities
|
- Session A: Open `~/github/superclaude/` (main)
|
||||||
3. **KNOWLEDGE.md** - Accumulated insights and troubleshooting
|
- Session B: Open `~/github/superclaude-integration/` (integration)
|
||||||
|
- Session C: Open `~/github/superclaude-feature/` (feature branch)
|
||||||
|
|
||||||
These documents are the **source of truth** for development standards.
|
**Cleanup**:
|
||||||
|
```bash
|
||||||
|
git worktree remove ../superclaude-integration
|
||||||
|
```
|
||||||
|
|
||||||
**Additional Resources:**
|
## 📝 Key Documentation Files
|
||||||
- User guides: `docs/user-guide/`
|
|
||||||
- Development docs: `docs/Development/`
|
**PLANNING.md** - Architecture, design principles, absolute rules
|
||||||
- Research reports: `docs/research/`
|
**TASK.md** - Current tasks and priorities
|
||||||
|
**KNOWLEDGE.md** - Accumulated insights and troubleshooting
|
||||||
|
|
||||||
|
Additional docs in `docs/user-guide/`, `docs/developer-guide/`, `docs/reference/`
|
||||||
|
|
||||||
## 💡 Core Development Principles
|
## 💡 Core Development Principles
|
||||||
|
|
||||||
From KNOWLEDGE.md and PLANNING.md:
|
|
||||||
|
|
||||||
### 1. Evidence-Based Development
|
### 1. Evidence-Based Development
|
||||||
- **Never guess** - verify with official docs (Context7 MCP, WebFetch, WebSearch)
|
**Never guess** - verify with official docs (Context7 MCP, WebFetch, WebSearch) before implementation.
|
||||||
- Example: Don't assume port configuration - check official documentation first
|
|
||||||
- Prevents wrong-direction implementations
|
|
||||||
|
|
||||||
### 2. Token Efficiency
|
### 2. Confidence-First Implementation
|
||||||
- Every operation has a token budget:
|
Check confidence BEFORE starting: ≥90% proceed, 70-89% present alternatives, <70% ask questions.
|
||||||
- Simple (typo fix): 200 tokens
|
|
||||||
- Medium (bug fix): 1,000 tokens
|
|
||||||
- Complex (feature): 2,500 tokens
|
|
||||||
- Confidence check ROI: Spend 100-200 to save 5,000-50,000
|
|
||||||
|
|
||||||
### 3. Parallel-First Execution
|
### 3. Parallel-First Execution
|
||||||
- **Wave → Checkpoint → Wave** pattern (3.5x faster)
|
Use **Wave → Checkpoint → Wave** pattern (3.5x faster). Example: `[Read files in parallel]` → Analyze → `[Edit files in parallel]`
|
||||||
- Good: `[Read file1, Read file2, Read file3]` → Analyze → `[Edit file1, Edit file2, Edit file3]`
|
|
||||||
- Bad: Sequential reads then sequential edits
|
|
||||||
|
|
||||||
### 4. Confidence-First Implementation
|
### 4. Token Efficiency
|
||||||
- Check confidence BEFORE implementation, not after
|
- Simple (typo): 200 tokens
|
||||||
- ≥90%: Proceed immediately
|
- Medium (bug fix): 1,000 tokens
|
||||||
- 70-89%: Present alternatives
|
- Complex (feature): 2,500 tokens
|
||||||
- <70%: STOP → Ask specific questions
|
- Confidence check ROI: spend 100-200 to save 5,000-50,000
|
||||||
|
|
||||||
## 🔧 MCP Server Integration
|
## 🔧 MCP Server Integration
|
||||||
|
|
||||||
This framework integrates with multiple MCP servers via **airis-mcp-gateway**:
|
Integrates with multiple MCP servers via **airis-mcp-gateway**.
|
||||||
|
|
||||||
**Priority Servers:**
|
**High Priority**:
|
||||||
- **Tavily**: Primary web search (Deep Research plugin)
|
- **Tavily**: Web search (Deep Research)
|
||||||
- **Serena**: Session persistence and memory
|
|
||||||
- **Mindbase**: Cross-session learning (zero-footprint)
|
|
||||||
- **Sequential**: Token-efficient reasoning (30-50% reduction)
|
|
||||||
- **Context7**: Official documentation (prevent hallucination)
|
- **Context7**: Official documentation (prevent hallucination)
|
||||||
|
- **Sequential**: Token-efficient reasoning (30-50% reduction)
|
||||||
|
- **Serena**: Session persistence
|
||||||
|
- **Mindbase**: Cross-session learning
|
||||||
|
|
||||||
**Optional Servers:**
|
**Optional**: Playwright (browser automation), Magic (UI components), Chrome DevTools (performance)
|
||||||
- **Playwright**: JavaScript-heavy content extraction
|
|
||||||
- **Magic**: UI component generation
|
|
||||||
- **Chrome DevTools**: Performance analysis
|
|
||||||
|
|
||||||
**Integration Pattern:**
|
**Usage**: TypeScript plugins and Python pytest plugin can call MCP servers. Always prefer MCP tools over speculation for documentation/research.
|
||||||
- TypeScript plugins call MCP servers directly
|
|
||||||
- Python pytest plugin uses MCP for test validation
|
|
||||||
- Always prefer MCP tools over speculation when documentation or research is needed
|
|
||||||
|
|
||||||
**Unified Gateway:**
|
|
||||||
- All MCP servers accessible via airis-mcp-gateway
|
|
||||||
- Simplified configuration and tool selection
|
|
||||||
- See: https://github.com/airis-mcp-gateway
|
|
||||||
|
|
||||||
## 🔗 Related
|
|
||||||
|
|
||||||
- Global rules: `~/.claude/CLAUDE.md` (workspace-level)
|
|
||||||
- MCP servers: Unified gateway via `airis-mcp-gateway`
|
|
||||||
- Framework docs: Auto-installed to `~/.claude/superclaude/`
|
|
||||||
|
|||||||
87
Makefile
87
Makefile
@@ -1,4 +1,4 @@
|
|||||||
.PHONY: dev install test test-plugin doctor verify clean lint format help
|
.PHONY: dev install test test-plugin doctor verify clean lint format install-plugin install-plugin-minimal install-plugin-dev uninstall-plugin reinstall-plugin reinstall-plugin-minimal reinstall-plugin-dev help
|
||||||
|
|
||||||
# Development installation (local source, editable) - RECOMMENDED
|
# Development installation (local source, editable) - RECOMMENDED
|
||||||
dev:
|
dev:
|
||||||
@@ -64,6 +64,82 @@ clean:
|
|||||||
find . -type d -name .pytest_cache -exec rm -rf {} +
|
find . -type d -name .pytest_cache -exec rm -rf {} +
|
||||||
find . -type d -name .ruff_cache -exec rm -rf {} +
|
find . -type d -name .ruff_cache -exec rm -rf {} +
|
||||||
|
|
||||||
|
# Install Claude Code plugin - MINIMAL (manifest only, for baseline performance)
|
||||||
|
install-plugin-minimal:
|
||||||
|
@echo "🔌 Installing SuperClaude plugin (MINIMAL) to Claude Code..."
|
||||||
|
@if [ -d ~/.claude/plugins/pm-agent ]; then \
|
||||||
|
echo "⚠️ Plugin already exists at ~/.claude/plugins/pm-agent"; \
|
||||||
|
echo " Run 'make reinstall-plugin-minimal' to update"; \
|
||||||
|
exit 1; \
|
||||||
|
fi
|
||||||
|
@mkdir -p ~/.claude/plugins/pm-agent
|
||||||
|
@cp .claude-plugin/plugin.json ~/.claude/plugins/pm-agent/
|
||||||
|
@cp .claude-plugin/marketplace.json ~/.claude/plugins/pm-agent/
|
||||||
|
@echo ""
|
||||||
|
@echo "✅ Plugin installed (MINIMAL configuration)"
|
||||||
|
@echo " Only manifest files copied - for baseline performance testing"
|
||||||
|
@echo ""
|
||||||
|
@echo "🔄 Restart Claude Code to activate plugins"
|
||||||
|
|
||||||
|
# Install Claude Code plugin - DEV (full, for development)
|
||||||
|
install-plugin-dev:
|
||||||
|
@echo "🔌 Installing SuperClaude plugin (DEV) to Claude Code..."
|
||||||
|
@if [ -d ~/.claude/plugins/pm-agent ]; then \
|
||||||
|
echo "⚠️ Plugin already exists at ~/.claude/plugins/pm-agent"; \
|
||||||
|
echo " Run 'make reinstall-plugin-dev' to update"; \
|
||||||
|
exit 1; \
|
||||||
|
fi
|
||||||
|
@mkdir -p ~/.claude/plugins/pm-agent
|
||||||
|
@cp -r .claude-plugin/* ~/.claude/plugins/pm-agent/
|
||||||
|
@cp -r commands ~/.claude/plugins/pm-agent/
|
||||||
|
@cp -r hooks ~/.claude/plugins/pm-agent/
|
||||||
|
@echo ""
|
||||||
|
@echo "✅ Plugin installed (DEV configuration)"
|
||||||
|
@echo ""
|
||||||
|
@echo "📋 Installed components:"
|
||||||
|
@echo " - /pm: PM Agent orchestrator (SessionStart hook)"
|
||||||
|
@echo " - /research: Deep web search with adaptive planning"
|
||||||
|
@echo " - /index-repo: Repository indexing (94%% token reduction)"
|
||||||
|
@echo ""
|
||||||
|
@echo "🔄 Restart Claude Code to activate plugins"
|
||||||
|
|
||||||
|
# Default install (dev configuration for backward compatibility)
|
||||||
|
install-plugin: install-plugin-dev
|
||||||
|
|
||||||
|
# Uninstall Claude Code plugin
|
||||||
|
uninstall-plugin:
|
||||||
|
@echo "🗑️ Uninstalling SuperClaude plugin..."
|
||||||
|
@if [ ! -d ~/.claude/plugins/pm-agent ]; then \
|
||||||
|
echo "❌ Plugin not found at ~/.claude/plugins/pm-agent"; \
|
||||||
|
exit 1; \
|
||||||
|
fi
|
||||||
|
@rm -rf ~/.claude/plugins/pm-agent
|
||||||
|
@echo "✅ Plugin uninstalled successfully"
|
||||||
|
|
||||||
|
# Reinstall plugin - MINIMAL
|
||||||
|
reinstall-plugin-minimal:
|
||||||
|
@echo "🔄 Reinstalling SuperClaude plugin (MINIMAL)..."
|
||||||
|
@rm -rf ~/.claude/plugins/pm-agent 2>/dev/null || true
|
||||||
|
@mkdir -p ~/.claude/plugins/pm-agent
|
||||||
|
@cp .claude-plugin/plugin.json ~/.claude/plugins/pm-agent/
|
||||||
|
@cp .claude-plugin/marketplace.json ~/.claude/plugins/pm-agent/
|
||||||
|
@echo "✅ Plugin reinstalled (MINIMAL configuration)"
|
||||||
|
@echo "🔄 Restart Claude Code to apply changes"
|
||||||
|
|
||||||
|
# Reinstall plugin - DEV
|
||||||
|
reinstall-plugin-dev:
|
||||||
|
@echo "🔄 Reinstalling SuperClaude plugin (DEV)..."
|
||||||
|
@rm -rf ~/.claude/plugins/pm-agent 2>/dev/null || true
|
||||||
|
@mkdir -p ~/.claude/plugins/pm-agent
|
||||||
|
@cp -r .claude-plugin/* ~/.claude/plugins/pm-agent/
|
||||||
|
@cp -r commands ~/.claude/plugins/pm-agent/
|
||||||
|
@cp -r hooks ~/.claude/plugins/pm-agent/
|
||||||
|
@echo "✅ Plugin reinstalled (DEV configuration)"
|
||||||
|
@echo "🔄 Restart Claude Code to apply changes"
|
||||||
|
|
||||||
|
# Default reinstall (dev configuration for backward compatibility)
|
||||||
|
reinstall-plugin: reinstall-plugin-dev
|
||||||
|
|
||||||
# Translate README to multiple languages using Neural CLI
|
# Translate README to multiple languages using Neural CLI
|
||||||
translate:
|
translate:
|
||||||
@echo "🌐 Translating README using Neural CLI (Ollama + qwen2.5:3b)..."
|
@echo "🌐 Translating README using Neural CLI (Ollama + qwen2.5:3b)..."
|
||||||
@@ -99,13 +175,14 @@ help:
|
|||||||
@echo " make format - Format code (ruff format)"
|
@echo " make format - Format code (ruff format)"
|
||||||
@echo " make clean - Clean build artifacts"
|
@echo " make clean - Clean build artifacts"
|
||||||
@echo ""
|
@echo ""
|
||||||
|
@echo "🔌 Plugin Management:"
|
||||||
|
@echo " make install-plugin - Install plugin to Claude Code (~/.claude/plugins/)"
|
||||||
|
@echo " make uninstall-plugin - Remove plugin from Claude Code"
|
||||||
|
@echo " make reinstall-plugin - Update existing plugin installation"
|
||||||
|
@echo ""
|
||||||
@echo "📚 Documentation:"
|
@echo "📚 Documentation:"
|
||||||
@echo " make translate - Translate README to Chinese and Japanese"
|
@echo " make translate - Translate README to Chinese and Japanese"
|
||||||
@echo " make help - Show this help message"
|
@echo " make help - Show this help message"
|
||||||
@echo ""
|
@echo ""
|
||||||
@echo "💡 Plugin Usage:"
|
|
||||||
@echo " cd /path/to/SuperClaude_Framework && claude"
|
|
||||||
@echo " → .claude-plugin/ auto-detected (project-local plugin)"
|
|
||||||
@echo ""
|
|
||||||
@echo "💡 Legacy (backward compatibility):"
|
@echo "💡 Legacy (backward compatibility):"
|
||||||
@echo " make install - Alias for 'make dev'"
|
@echo " make install - Alias for 'make dev'"
|
||||||
|
|||||||
161
PLUGIN_INSTALL.md
Normal file
161
PLUGIN_INSTALL.md
Normal file
@@ -0,0 +1,161 @@
|
|||||||
|
# SuperClaude Plugin Installation Guide
|
||||||
|
|
||||||
|
## 公式インストール方法（推奨）
|
||||||
|
|
||||||
|
### 前提条件
|
||||||
|
|
||||||
|
1. **ripgrep のインストール**
|
||||||
|
```bash
|
||||||
|
brew install ripgrep
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **環境変数の設定**（~/.zshrc または ~/.bashrc に追加）
|
||||||
|
```bash
|
||||||
|
export USE_BUILTIN_RIPGREP=0
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **シェルの再起動**
|
||||||
|
```bash
|
||||||
|
exec $SHELL
|
||||||
|
```
|
||||||
|
|
||||||
|
### インストール手順
|
||||||
|
|
||||||
|
#### 方法A: ローカルマーケットプレイス経由（推奨）
|
||||||
|
|
||||||
|
1. Claude Code でマーケットプレイスを追加:
|
||||||
|
```
|
||||||
|
/plugin marketplace add /Users/kazuki/github/superclaude
|
||||||
|
```
|
||||||
|
|
||||||
|
2. プラグインをインストール:
|
||||||
|
```
|
||||||
|
/plugin install pm-agent@superclaude-local
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Claude Code を再起動
|
||||||
|
|
||||||
|
4. 動作確認:
|
||||||
|
```
|
||||||
|
/pm
|
||||||
|
/research
|
||||||
|
/index-repo
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 方法B: 開発者モード（直接コピー）
|
||||||
|
|
||||||
|
**注意**: この方法は開発中のテスト用です。公式方法（方法A）の使用を推奨します。
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# プロジェクトルートで実行
|
||||||
|
make reinstall-plugin-dev
|
||||||
|
```
|
||||||
|
|
||||||
|
Claude Code を再起動後、コマンドが利用可能になります。
|
||||||
|
|
||||||
|
## インストールされるコマンド
|
||||||
|
|
||||||
|
### /pm
|
||||||
|
PM Agent モードを起動。以下の機能を提供：
|
||||||
|
- 90%信頼度チェック（実装前）
|
||||||
|
- 並列実行最適化
|
||||||
|
- トークン予算管理
|
||||||
|
- エビデンスベース開発
|
||||||
|
|
||||||
|
### /research
|
||||||
|
Deep Research モード。以下の機能を提供：
|
||||||
|
- 並列Web検索（Tavily MCP）
|
||||||
|
- 公式ドキュメント優先
|
||||||
|
- ソース検証
|
||||||
|
- 信頼度付き結果
|
||||||
|
|
||||||
|
### /index-repo
|
||||||
|
リポジトリインデックス作成。以下の機能を提供：
|
||||||
|
- プロジェクト構造解析
|
||||||
|
- 94%トークン削減（58K → 3K）
|
||||||
|
- エントリポイント特定
|
||||||
|
- モジュールマップ生成
|
||||||
|
|
||||||
|
## フックの自動実行
|
||||||
|
|
||||||
|
SessionStart フックにより、新しいセッション開始時に `/pm` コマンドが自動実行されます。
|
||||||
|
|
||||||
|
無効化したい場合は、`~/.claude/plugins/pm-agent/hooks/hooks.json` を編集してください。
|
||||||
|
|
||||||
|
## トラブルシューティング
|
||||||
|
|
||||||
|
### コマンドが認識されない場合
|
||||||
|
|
||||||
|
1. **ripgrep の確認**:
|
||||||
|
```bash
|
||||||
|
which rg
|
||||||
|
rg --version
|
||||||
|
```
|
||||||
|
|
||||||
|
インストールされていない場合：
|
||||||
|
```bash
|
||||||
|
brew install ripgrep
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **環境変数の確認**:
|
||||||
|
```bash
|
||||||
|
echo $USE_BUILTIN_RIPGREP
|
||||||
|
```
|
||||||
|
|
||||||
|
設定されていない場合：
|
||||||
|
```bash
|
||||||
|
echo 'export USE_BUILTIN_RIPGREP=0' >> ~/.zshrc
|
||||||
|
exec $SHELL
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **プラグインの確認**:
|
||||||
|
```bash
|
||||||
|
ls -la ~/.claude/plugins/pm-agent/
|
||||||
|
```
|
||||||
|
|
||||||
|
存在しない場合は再インストール：
|
||||||
|
```bash
|
||||||
|
make reinstall-plugin-dev
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Claude Code を再起動**
|
||||||
|
|
||||||
|
### それでも動かない場合
|
||||||
|
|
||||||
|
Claude Code のバージョンを確認してください。2.0.x には既知のバグがあります：
|
||||||
|
- GitHub Issue #8831: Custom slash commands not discovered
|
||||||
|
|
||||||
|
回避策：
|
||||||
|
- NPM版に切り替える（Homebrew版にバグの可能性）
|
||||||
|
- ripgrep をシステムにインストール（上記手順）
|
||||||
|
|
||||||
|
## プラグイン構造（参考）
|
||||||
|
|
||||||
|
```
|
||||||
|
~/.claude/plugins/pm-agent/
|
||||||
|
├── plugin.json # プラグインメタデータ
|
||||||
|
├── marketplace.json # マーケットプレイス情報
|
||||||
|
├── commands/ # Markdown コマンド
|
||||||
|
│ ├── pm.md
|
||||||
|
│ ├── research.md
|
||||||
|
│ └── index-repo.md
|
||||||
|
└── hooks/
|
||||||
|
└── hooks.json # SessionStart フック設定
|
||||||
|
```
|
||||||
|
|
||||||
|
## 開発者向け情報
|
||||||
|
|
||||||
|
プラグインのソースコードは `/Users/kazuki/github/superclaude/` にあります。
|
||||||
|
|
||||||
|
変更を反映するには：
|
||||||
|
```bash
|
||||||
|
make reinstall-plugin-dev
|
||||||
|
# Claude Code を再起動
|
||||||
|
```
|
||||||
|
|
||||||
|
## サポート
|
||||||
|
|
||||||
|
問題が発生した場合は、以下を確認してください：
|
||||||
|
- 公式ドキュメント: https://docs.claude.com/ja/docs/claude-code/plugins
|
||||||
|
- GitHub Issues: https://github.com/anthropics/claude-code/issues
|
||||||
|
- プロジェクトドキュメント: CLAUDE.md, PLANNING.md
|
||||||
165
commands/index-repo.md
Normal file
165
commands/index-repo.md
Normal file
@@ -0,0 +1,165 @@
|
|||||||
|
---
|
||||||
|
name: index-repo
|
||||||
|
description: Repository Indexing - 94% token reduction (58K → 3K)
|
||||||
|
---
|
||||||
|
|
||||||
|
# Repository Index Creator
|
||||||
|
|
||||||
|
📊 **Index Creator activated**
|
||||||
|
|
||||||
|
## Problem Statement
|
||||||
|
|
||||||
|
**Before**: Reading all files → 58,000 tokens every session
|
||||||
|
**After**: Read PROJECT_INDEX.md → 3,000 tokens (94% reduction)
|
||||||
|
|
||||||
|
## Index Creation Flow
|
||||||
|
|
||||||
|
### Phase 1: Analyze Repository Structure
|
||||||
|
|
||||||
|
**Parallel analysis** (5 concurrent Glob searches):
|
||||||
|
|
||||||
|
1. **Code Structure**
|
||||||
|
```
|
||||||
|
src/**/*.{ts,py,js,tsx,jsx}
|
||||||
|
lib/**/*.{ts,py,js}
|
||||||
|
superclaude/**/*.py
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Documentation**
|
||||||
|
```
|
||||||
|
docs/**/*.md
|
||||||
|
*.md (root level)
|
||||||
|
README*.md
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Configuration**
|
||||||
|
```
|
||||||
|
*.toml
|
||||||
|
*.yaml, *.yml
|
||||||
|
*.json (exclude package-lock, node_modules)
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Tests**
|
||||||
|
```
|
||||||
|
tests/**/*.{py,ts,js}
|
||||||
|
**/*.test.{ts,py,js}
|
||||||
|
**/*.spec.{ts,py,js}
|
||||||
|
```
|
||||||
|
|
||||||
|
5. **Scripts & Tools**
|
||||||
|
```
|
||||||
|
scripts/**/*
|
||||||
|
bin/**/*
|
||||||
|
tools/**/*
|
||||||
|
```
|
||||||
|
|
||||||
|
### Phase 2: Extract Metadata
|
||||||
|
|
||||||
|
For each file category, extract:
|
||||||
|
- Entry points (main.py, index.ts, cli.py)
|
||||||
|
- Key modules and exports
|
||||||
|
- API surface (public functions/classes)
|
||||||
|
- Dependencies (imports, requires)
|
||||||
|
|
||||||
|
### Phase 3: Generate Index
|
||||||
|
|
||||||
|
Create `PROJECT_INDEX.md` with structure:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Project Index: {project_name}
|
||||||
|
|
||||||
|
Generated: {timestamp}
|
||||||
|
|
||||||
|
## 📁 Project Structure
|
||||||
|
|
||||||
|
{tree view of main directories}
|
||||||
|
|
||||||
|
## 🚀 Entry Points
|
||||||
|
|
||||||
|
- CLI: {path} - {description}
|
||||||
|
- API: {path} - {description}
|
||||||
|
- Tests: {path} - {description}
|
||||||
|
|
||||||
|
## 📦 Core Modules
|
||||||
|
|
||||||
|
### Module: {name}
|
||||||
|
- Path: {path}
|
||||||
|
- Exports: {list}
|
||||||
|
- Purpose: {1-line description}
|
||||||
|
|
||||||
|
## 🔧 Configuration
|
||||||
|
|
||||||
|
- {config_file}: {purpose}
|
||||||
|
|
||||||
|
## 📚 Documentation
|
||||||
|
|
||||||
|
- {doc_file}: {topic}
|
||||||
|
|
||||||
|
## 🧪 Test Coverage
|
||||||
|
|
||||||
|
- Unit tests: {count} files
|
||||||
|
- Integration tests: {count} files
|
||||||
|
- Coverage: {percentage}%
|
||||||
|
|
||||||
|
## 🔗 Key Dependencies
|
||||||
|
|
||||||
|
- {dependency}: {version} - {purpose}
|
||||||
|
|
||||||
|
## 📝 Quick Start
|
||||||
|
|
||||||
|
1. {setup step}
|
||||||
|
2. {run step}
|
||||||
|
3. {test step}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Phase 4: Validation
|
||||||
|
|
||||||
|
Quality checks:
|
||||||
|
- [ ] All entry points identified?
|
||||||
|
- [ ] Core modules documented?
|
||||||
|
- [ ] Index size < 5KB?
|
||||||
|
- [ ] Human-readable format?
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
**Create index**:
|
||||||
|
```
|
||||||
|
/index-repo
|
||||||
|
```
|
||||||
|
|
||||||
|
**Update existing index**:
|
||||||
|
```
|
||||||
|
/index-repo mode=update
|
||||||
|
```
|
||||||
|
|
||||||
|
**Quick index (skip tests)**:
|
||||||
|
```
|
||||||
|
/index-repo mode=quick
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Token Efficiency
|
||||||
|
|
||||||
|
**ROI Calculation**:
|
||||||
|
- Index creation: 2,000 tokens (one-time)
|
||||||
|
- Index reading: 3,000 tokens (every session)
|
||||||
|
- Full codebase read: 58,000 tokens (every session)
|
||||||
|
|
||||||
|
**Break-even**: 1 session
|
||||||
|
**10 sessions savings**: 550,000 tokens
|
||||||
|
**100 sessions savings**: 5,500,000 tokens
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Output Format
|
||||||
|
|
||||||
|
Creates two files:
|
||||||
|
1. `PROJECT_INDEX.md` (3KB, human-readable)
|
||||||
|
2. `PROJECT_INDEX.json` (10KB, machine-readable)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Index Creator is now active.** Run to analyze current repository.
|
||||||
240
commands/pm.md
Normal file
240
commands/pm.md
Normal file
@@ -0,0 +1,240 @@
|
|||||||
|
---
|
||||||
|
name: pm
|
||||||
|
description: PM Agent - Confidence-driven workflow orchestrator
|
||||||
|
---
|
||||||
|
|
||||||
|
# PM Agent Activation
|
||||||
|
|
||||||
|
🚀 **PM Agent activated**
|
||||||
|
|
||||||
|
## Session Start Protocol
|
||||||
|
|
||||||
|
**IMMEDIATELY execute the following checks:**
|
||||||
|
|
||||||
|
1. **Git Status Check**
|
||||||
|
- Run `git status --porcelain`
|
||||||
|
- Display: `📊 Git: {clean | X file(s) modified | not a git repo}`
|
||||||
|
|
||||||
|
2. **Token Budget Awareness**
|
||||||
|
- Display: `💡 Check token budget with /context`
|
||||||
|
|
||||||
|
3. **Ready Message**
|
||||||
|
- Display startup message with core capabilities
|
||||||
|
|
||||||
|
```
|
||||||
|
✅ PM Agent ready to accept tasks
|
||||||
|
|
||||||
|
**Core Capabilities**:
|
||||||
|
- 🔍 Pre-implementation confidence check (≥90% required)
|
||||||
|
- ⚡ Parallel investigation and execution
|
||||||
|
- 📊 Token-budget-aware operations
|
||||||
|
|
||||||
|
**Usage**: Assign tasks directly - PM Agent will orchestrate
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Confidence-Driven Workflow
|
||||||
|
|
||||||
|
**CRITICAL**: When user assigns a task, follow this EXACT protocol:
|
||||||
|
|
||||||
|
### Phase 1: Investigation Loop
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
- `MAX_ITERATIONS = 10`
|
||||||
|
- `confidence_threshold = 0.90` (90%)
|
||||||
|
- `iteration = 0`
|
||||||
|
- `confidence = 0.0`
|
||||||
|
|
||||||
|
**Loop Protocol:**
|
||||||
|
```
|
||||||
|
WHILE confidence < 0.90 AND iteration < MAX_ITERATIONS:
|
||||||
|
iteration++
|
||||||
|
|
||||||
|
Display: "🔄 Investigation iteration {iteration}..."
|
||||||
|
|
||||||
|
Execute Investigation Phase (see below)
|
||||||
|
|
||||||
|
Execute Confidence Check (see below)
|
||||||
|
|
||||||
|
Display: "📊 Confidence: {confidence}%"
|
||||||
|
|
||||||
|
IF confidence < 0.90:
|
||||||
|
Display: "⚠️ Confidence < 90% - Continue investigation"
|
||||||
|
CONTINUE loop
|
||||||
|
ELSE:
|
||||||
|
BREAK loop
|
||||||
|
END WHILE
|
||||||
|
|
||||||
|
IF confidence >= 0.90:
|
||||||
|
Display: "✅ High confidence (≥90%) - Proceeding to implementation"
|
||||||
|
Execute Implementation Phase
|
||||||
|
ELSE:
|
||||||
|
Display: "❌ Max iterations reached - Request user clarification"
|
||||||
|
ASK user for more context
|
||||||
|
END IF
|
||||||
|
```
|
||||||
|
|
||||||
|
### Phase 2: Investigation Phase
|
||||||
|
|
||||||
|
**For EACH iteration, perform these checks in parallel:**
|
||||||
|
|
||||||
|
Use **Wave → Checkpoint → Wave** pattern:
|
||||||
|
|
||||||
|
**Wave 1: Parallel Investigation**
|
||||||
|
Execute these searches simultaneously (multiple tool calls in one message):
|
||||||
|
|
||||||
|
1. **Duplicate Check** (25% weight)
|
||||||
|
- `Grep` for similar function names
|
||||||
|
- `Glob` for related modules
|
||||||
|
- Check if functionality already exists
|
||||||
|
|
||||||
|
2. **Architecture Check** (25% weight)
|
||||||
|
- Read `CLAUDE.md`, `PLANNING.md`
|
||||||
|
- Verify tech stack compliance
|
||||||
|
- Check existing patterns
|
||||||
|
|
||||||
|
3. **Official Docs Verification** (20% weight)
|
||||||
|
- Search for library/framework docs
|
||||||
|
- Use Context7 MCP or WebFetch
|
||||||
|
- Verify API compatibility
|
||||||
|
|
||||||
|
4. **OSS Reference Search** (15% weight)
|
||||||
|
- Use Tavily MCP or WebSearch
|
||||||
|
- Find working implementations
|
||||||
|
- Check GitHub examples
|
||||||
|
|
||||||
|
5. **Root Cause Analysis** (15% weight)
|
||||||
|
- Analyze error messages
|
||||||
|
- Check logs, stack traces
|
||||||
|
- Identify actual problem source
|
||||||
|
|
||||||
|
**Checkpoint: Analyze Results**
|
||||||
|
|
||||||
|
After all parallel searches complete, synthesize findings.
|
||||||
|
|
||||||
|
### Phase 3: Confidence Check
|
||||||
|
|
||||||
|
**Calculate confidence score (0.0 - 1.0):**
|
||||||
|
|
||||||
|
```
|
||||||
|
confidence = 0.0
|
||||||
|
|
||||||
|
Check 1: No Duplicate Implementations? (25%)
|
||||||
|
IF duplicate_check_complete:
|
||||||
|
confidence += 0.25
|
||||||
|
Display: "✅ No duplicate implementations found"
|
||||||
|
ELSE:
|
||||||
|
Display: "❌ Check for existing implementations first"
|
||||||
|
|
||||||
|
Check 2: Architecture Compliance? (25%)
|
||||||
|
IF architecture_check_complete:
|
||||||
|
confidence += 0.25
|
||||||
|
Display: "✅ Uses existing tech stack"
|
||||||
|
ELSE:
|
||||||
|
Display: "❌ Verify architecture compliance (avoid reinventing)"
|
||||||
|
|
||||||
|
Check 3: Official Documentation Verified? (20%)
|
||||||
|
IF official_docs_verified:
|
||||||
|
confidence += 0.20
|
||||||
|
Display: "✅ Official documentation verified"
|
||||||
|
ELSE:
|
||||||
|
Display: "❌ Read official docs first"
|
||||||
|
|
||||||
|
Check 4: Working OSS Implementation Referenced? (15%)
|
||||||
|
IF oss_reference_complete:
|
||||||
|
confidence += 0.15
|
||||||
|
Display: "✅ Working OSS implementation found"
|
||||||
|
ELSE:
|
||||||
|
Display: "❌ Search for OSS implementations"
|
||||||
|
|
||||||
|
Check 5: Root Cause Identified? (15%)
|
||||||
|
IF root_cause_identified:
|
||||||
|
confidence += 0.15
|
||||||
|
Display: "✅ Root cause identified"
|
||||||
|
ELSE:
|
||||||
|
Display: "❌ Continue investigation to identify root cause"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Display Confidence Checks:**
|
||||||
|
```
|
||||||
|
📋 Confidence Checks:
|
||||||
|
{check 1 result}
|
||||||
|
{check 2 result}
|
||||||
|
{check 3 result}
|
||||||
|
{check 4 result}
|
||||||
|
{check 5 result}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Phase 4: Implementation Phase
|
||||||
|
|
||||||
|
**ONLY execute when confidence ≥ 90%**
|
||||||
|
|
||||||
|
1. **Plan implementation** based on investigation findings
|
||||||
|
2. **Use parallel execution** (Wave pattern) for file edits
|
||||||
|
3. **Verify with tests** (no speculation)
|
||||||
|
4. **Self-check** post-implementation
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Token Budget Allocation
|
||||||
|
|
||||||
|
- **Simple** (typo fix): 200 tokens
|
||||||
|
- **Medium** (bug fix): 1,000 tokens
|
||||||
|
- **Complex** (feature): 2,500 tokens
|
||||||
|
|
||||||
|
**Confidence Check ROI**: Spend 100-200 tokens to save 5,000-50,000 tokens
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## MCP Server Integration
|
||||||
|
|
||||||
|
**Prefer MCP tools over speculation:**
|
||||||
|
|
||||||
|
- **Context7**: Official documentation lookup (prevent hallucination)
|
||||||
|
- **Tavily**: Deep web research
|
||||||
|
- **Sequential**: Token-efficient reasoning (30-50% reduction)
|
||||||
|
- **Serena**: Session persistence
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Evidence-Based Development
|
||||||
|
|
||||||
|
**NEVER guess** - always verify with:
|
||||||
|
1. Official documentation (Context7 MCP, WebFetch)
|
||||||
|
2. Actual codebase (Read, Grep, Glob)
|
||||||
|
3. Tests (pytest, uv run pytest)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Parallel Execution Pattern
|
||||||
|
|
||||||
|
**Wave → Checkpoint → Wave**:
|
||||||
|
- **Wave 1**: [Read files in parallel] using multiple tool calls in one message
|
||||||
|
- **Checkpoint**: Analyze results, plan next wave
|
||||||
|
- **Wave 2**: [Edit files in parallel] based on analysis
|
||||||
|
|
||||||
|
**Performance**: 3.5x faster than sequential execution
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Self-Check Protocol (Post-Implementation)
|
||||||
|
|
||||||
|
After implementation:
|
||||||
|
1. Verify with tests/docs (NO speculation)
|
||||||
|
2. Check for edge cases and error handling
|
||||||
|
3. Validate against requirements
|
||||||
|
4. If errors: Record pattern, store prevention strategy
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Memory Management
|
||||||
|
|
||||||
|
**Zero-footprint**: No auto-load, explicit load/save only
|
||||||
|
|
||||||
|
- Load: Use Serena MCP `read_memory`
|
||||||
|
- Save: Use Serena MCP `write_memory`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**PM Agent is now active.** When you receive a task, IMMEDIATELY begin the Confidence-Driven Workflow loop.
|
||||||
122
commands/research.md
Normal file
122
commands/research.md
Normal file
@@ -0,0 +1,122 @@
|
|||||||
|
---
|
||||||
|
name: research
|
||||||
|
description: Deep Research - Parallel web search with evidence-based synthesis
|
||||||
|
---
|
||||||
|
|
||||||
|
# Deep Research Agent
|
||||||
|
|
||||||
|
🔍 **Deep Research activated**
|
||||||
|
|
||||||
|
## Research Protocol
|
||||||
|
|
||||||
|
Execute adaptive, parallel-first web research with evidence-based synthesis.
|
||||||
|
|
||||||
|
### Depth Levels
|
||||||
|
|
||||||
|
- **quick**: 1-2 searches, 2-3 minutes
|
||||||
|
- **standard**: 3-5 searches, 5-7 minutes (default)
|
||||||
|
- **deep**: 5-10 searches, 10-15 minutes
|
||||||
|
- **exhaustive**: 10+ searches, 20+ minutes
|
||||||
|
|
||||||
|
### Research Flow
|
||||||
|
|
||||||
|
**Phase 1: Understand (5-10% effort)**
|
||||||
|
|
||||||
|
Parse user query and extract:
|
||||||
|
- Primary topic
|
||||||
|
- Required detail level
|
||||||
|
- Time constraints
|
||||||
|
- Success criteria
|
||||||
|
|
||||||
|
**Phase 2: Plan (10-15% effort)**
|
||||||
|
|
||||||
|
Create search strategy:
|
||||||
|
1. Identify key concepts
|
||||||
|
2. Plan parallel search queries
|
||||||
|
3. Select sources (official docs, GitHub, technical blogs)
|
||||||
|
4. Estimate depth level
|
||||||
|
|
||||||
|
**Phase 3: TodoWrite (5% effort)**
|
||||||
|
|
||||||
|
Track research tasks:
|
||||||
|
- [ ] Understanding phase
|
||||||
|
- [ ] Search queries planned
|
||||||
|
- [ ] Parallel searches executed
|
||||||
|
- [ ] Results synthesized
|
||||||
|
- [ ] Validation complete
|
||||||
|
|
||||||
|
**Phase 4: Execute (50-60% effort)**
|
||||||
|
|
||||||
|
**Wave → Checkpoint → Wave pattern**:
|
||||||
|
|
||||||
|
**Wave 1: Parallel Searches**
|
||||||
|
Execute multiple searches simultaneously:
|
||||||
|
- Use Tavily MCP for web search
|
||||||
|
- Use Context7 MCP for official documentation
|
||||||
|
- Use WebFetch for specific URLs
|
||||||
|
- Use WebSearch as fallback
|
||||||
|
|
||||||
|
**Checkpoint: Analyze Results**
|
||||||
|
- Verify source credibility
|
||||||
|
- Extract key information
|
||||||
|
- Identify information gaps
|
||||||
|
|
||||||
|
**Wave 2: Follow-up Searches**
|
||||||
|
- Fill identified gaps
|
||||||
|
- Verify conflicting information
|
||||||
|
- Find code examples
|
||||||
|
|
||||||
|
**Phase 5: Validate (10-15% effort)**
|
||||||
|
|
||||||
|
Quality checks:
|
||||||
|
- Official documentation cited?
|
||||||
|
- Multiple sources confirm findings?
|
||||||
|
- Code examples verified?
|
||||||
|
- Confidence score ≥ 0.85?
|
||||||
|
|
||||||
|
**Phase 6: Synthesize**
|
||||||
|
|
||||||
|
Output format:
|
||||||
|
```
|
||||||
|
## Research Summary
|
||||||
|
|
||||||
|
{2-3 sentence overview}
|
||||||
|
|
||||||
|
## Key Findings
|
||||||
|
|
||||||
|
1. {Finding with source citation}
|
||||||
|
2. {Finding with source citation}
|
||||||
|
3. {Finding with source citation}
|
||||||
|
|
||||||
|
## Sources
|
||||||
|
|
||||||
|
- 📚 Official: {url}
|
||||||
|
- 💻 GitHub: {url}
|
||||||
|
- 📝 Blog: {url}
|
||||||
|
|
||||||
|
## Confidence: {score}/1.0
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## MCP Integration
|
||||||
|
|
||||||
|
**Primary**: Tavily (web search + extraction)
|
||||||
|
**Secondary**: Context7 (official docs), Sequential (reasoning), Playwright (JS content)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Parallel Execution
|
||||||
|
|
||||||
|
**ALWAYS execute searches in parallel** (multiple tool calls in one message):
|
||||||
|
|
||||||
|
```
|
||||||
|
Good: [Tavily search 1] + [Context7 lookup] + [WebFetch URL]
|
||||||
|
Bad: Execute search 1 → Wait → Execute search 2 → Wait
|
||||||
|
```
|
||||||
|
|
||||||
|
**Performance**: 3-5x faster than sequential
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Deep Research is now active.** Provide your research query to begin.
|
||||||
15
hooks/hooks.json
Normal file
15
hooks/hooks.json
Normal file
@@ -0,0 +1,15 @@
|
|||||||
|
{
|
||||||
|
"hooks": {
|
||||||
|
"SessionStart": [
|
||||||
|
{
|
||||||
|
"hooks": [
|
||||||
|
{
|
||||||
|
"type": "command",
|
||||||
|
"command": "/pm",
|
||||||
|
"timeout": 30
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
270
index/index.ts
Normal file
270
index/index.ts
Normal file
@@ -0,0 +1,270 @@
|
|||||||
|
/**
|
||||||
|
* Repository Indexing for Token Efficiency
|
||||||
|
*
|
||||||
|
* Problem: Loading全ファイルで毎回50,000トークン消費
|
||||||
|
* Solution: 最初だけインデックス作成、以降3,000トークンで済む (94%削減)
|
||||||
|
*
|
||||||
|
* Token Efficiency:
|
||||||
|
* Before: 58,000 tokens (read all files)
|
||||||
|
* After: 3,000 tokens (read PROJECT_INDEX.md)
|
||||||
|
* Savings: 94% (55,000 tokens)
|
||||||
|
*/
|
||||||
|
|
||||||
|
import { execSync } from 'child_process';
|
||||||
|
import { readdirSync, statSync, writeFileSync } from 'fs';
|
||||||
|
import { join } from 'path';
|
||||||
|
|
||||||
|
export interface IndexOptions {
|
||||||
|
root?: string;
|
||||||
|
mode?: 'full' | 'quick' | 'update';
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface IndexResult {
|
||||||
|
path: string;
|
||||||
|
files: number;
|
||||||
|
quality: number;
|
||||||
|
duration: number;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Create repository index
|
||||||
|
*
|
||||||
|
* Parallel analysis (5 concurrent tasks):
|
||||||
|
* 1. Code structure (src/, lib/, superclaude/)
|
||||||
|
* 2. Documentation (docs/, *.md)
|
||||||
|
* 3. Configuration (.toml, .yaml, .json)
|
||||||
|
* 4. Tests (tests/, **tests**)
|
||||||
|
* 5. Scripts (scripts/, bin/, tools/)
|
||||||
|
*
|
||||||
|
* Output:
|
||||||
|
* - PROJECT_INDEX.md (3KB, human-readable)
|
||||||
|
* - PROJECT_INDEX.json (10KB, machine-readable)
|
||||||
|
*
|
||||||
|
* @param options - Indexing configuration
|
||||||
|
* @returns Index result
|
||||||
|
*/
|
||||||
|
export async function createIndex(options: IndexOptions = {}): Promise<IndexResult> {
|
||||||
|
const { root = process.cwd(), mode = 'full' } = options;
|
||||||
|
|
||||||
|
console.log("================================================================================");
|
||||||
|
console.log("🚀 Parallel Repository Indexing");
|
||||||
|
console.log("================================================================================");
|
||||||
|
console.log(`Repository: ${root}`);
|
||||||
|
console.log(`Mode: ${mode}`);
|
||||||
|
console.log("================================================================================");
|
||||||
|
console.log("");
|
||||||
|
|
||||||
|
const startTime = Date.now();
|
||||||
|
|
||||||
|
// Check if index exists and is fresh
|
||||||
|
if (mode === 'update' && isIndexFresh(root)) {
|
||||||
|
console.log("✅ Index is fresh (< 7 days old) - skipping");
|
||||||
|
return {
|
||||||
|
path: join(root, 'PROJECT_INDEX.md'),
|
||||||
|
files: 0,
|
||||||
|
quality: 100,
|
||||||
|
duration: 0
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
console.log("📊 Executing parallel tasks...");
|
||||||
|
console.log("");
|
||||||
|
|
||||||
|
// Execute parallel tasks
|
||||||
|
const [codeStructure, documentation, configuration, tests, scripts] = await Promise.all([
|
||||||
|
analyzeCodeStructure(root),
|
||||||
|
analyzeDocumentation(root),
|
||||||
|
analyzeConfiguration(root),
|
||||||
|
analyzeTests(root),
|
||||||
|
analyzeScripts(root)
|
||||||
|
]);
|
||||||
|
|
||||||
|
console.log(` ✅ code_structure: ${codeStructure.duration}ms`);
|
||||||
|
console.log(` ✅ documentation: ${documentation.duration}ms`);
|
||||||
|
console.log(` ✅ configuration: ${configuration.duration}ms`);
|
||||||
|
console.log(` ✅ tests: ${tests.duration}ms`);
|
||||||
|
console.log(` ✅ scripts: ${scripts.duration}ms`);
|
||||||
|
console.log("");
|
||||||
|
|
||||||
|
// Generate index content
|
||||||
|
const index = generateIndex({
|
||||||
|
root,
|
||||||
|
codeStructure,
|
||||||
|
documentation,
|
||||||
|
configuration,
|
||||||
|
tests,
|
||||||
|
scripts
|
||||||
|
});
|
||||||
|
|
||||||
|
// Write outputs
|
||||||
|
const indexPath = join(root, 'PROJECT_INDEX.md');
|
||||||
|
const jsonPath = join(root, 'PROJECT_INDEX.json');
|
||||||
|
|
||||||
|
writeFileSync(indexPath, index.markdown);
|
||||||
|
writeFileSync(jsonPath, JSON.stringify(index.json, null, 2));
|
||||||
|
|
||||||
|
const duration = Date.now() - startTime;
|
||||||
|
|
||||||
|
console.log("================================================================================");
|
||||||
|
console.log(`✅ Indexing complete in ${(duration / 1000).toFixed(2)}s`);
|
||||||
|
console.log("================================================================================");
|
||||||
|
console.log("");
|
||||||
|
console.log(`💾 Index saved to: PROJECT_INDEX.md`);
|
||||||
|
console.log(`💾 JSON saved to: PROJECT_INDEX.json`);
|
||||||
|
console.log("");
|
||||||
|
console.log(`Files: ${index.totalFiles} | Quality: ${index.quality}/100`);
|
||||||
|
|
||||||
|
return {
|
||||||
|
path: indexPath,
|
||||||
|
files: index.totalFiles,
|
||||||
|
quality: index.quality,
|
||||||
|
duration
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Check if index is fresh (< 7 days old)
|
||||||
|
*/
|
||||||
|
function isIndexFresh(root: string): boolean {
|
||||||
|
try {
|
||||||
|
const stat = statSync(join(root, 'PROJECT_INDEX.md'));
|
||||||
|
const age = Date.now() - stat.mtimeMs;
|
||||||
|
const sevenDays = 7 * 24 * 60 * 60 * 1000;
|
||||||
|
return age < sevenDays;
|
||||||
|
} catch {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Analyze code structure
|
||||||
|
*/
|
||||||
|
async function analyzeCodeStructure(root: string): Promise<any> {
|
||||||
|
const start = Date.now();
|
||||||
|
// Find src/, lib/, superclaude/ directories
|
||||||
|
const files = findFiles(root, ['src', 'lib', 'superclaude'], ['.ts', '.js', '.py']);
|
||||||
|
return {
|
||||||
|
files,
|
||||||
|
duration: Date.now() - start
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Analyze documentation
|
||||||
|
*/
|
||||||
|
async function analyzeDocumentation(root: string): Promise<any> {
|
||||||
|
const start = Date.now();
|
||||||
|
// Find docs/ and *.md files
|
||||||
|
const files = findFiles(root, ['docs'], ['.md']);
|
||||||
|
return {
|
||||||
|
files,
|
||||||
|
duration: Date.now() - start
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Analyze configuration
|
||||||
|
*/
|
||||||
|
async function analyzeConfiguration(root: string): Promise<any> {
|
||||||
|
const start = Date.now();
|
||||||
|
// Find .toml, .yaml, .json files
|
||||||
|
const files = findFiles(root, [root], ['.toml', '.yaml', '.json']);
|
||||||
|
return {
|
||||||
|
files,
|
||||||
|
duration: Date.now() - start
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Analyze tests
|
||||||
|
*/
|
||||||
|
async function analyzeTests(root: string): Promise<any> {
|
||||||
|
const start = Date.now();
|
||||||
|
// Find tests/ directories
|
||||||
|
const files = findFiles(root, ['tests', 'test'], ['.ts', '.js', '.py']);
|
||||||
|
return {
|
||||||
|
files,
|
||||||
|
duration: Date.now() - start
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Analyze scripts
|
||||||
|
*/
|
||||||
|
async function analyzeScripts(root: string): Promise<any> {
|
||||||
|
const start = Date.now();
|
||||||
|
// Find scripts/, bin/, tools/ directories
|
||||||
|
const files = findFiles(root, ['scripts', 'bin', 'tools'], ['.sh', '.js', '.py']);
|
||||||
|
return {
|
||||||
|
files,
|
||||||
|
duration: Date.now() - start
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Find files in directories with extensions
|
||||||
|
*/
|
||||||
|
function findFiles(root: string, dirs: string[], extensions: string[]): string[] {
|
||||||
|
// Simplified file finder (real implementation would be more robust)
|
||||||
|
return [];
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Generate index content
|
||||||
|
*/
|
||||||
|
function generateIndex(data: any): any {
|
||||||
|
const totalFiles =
|
||||||
|
data.codeStructure.files.length +
|
||||||
|
data.documentation.files.length +
|
||||||
|
data.configuration.files.length +
|
||||||
|
data.tests.files.length +
|
||||||
|
data.scripts.files.length;
|
||||||
|
|
||||||
|
const markdown = `# Project Index
|
||||||
|
|
||||||
|
**Generated**: ${new Date().toISOString().split('T')[0]}
|
||||||
|
**Repository**: ${data.root}
|
||||||
|
**Total Files**: ${totalFiles}
|
||||||
|
**Quality Score**: 90/100
|
||||||
|
|
||||||
|
## 📂 Directory Structure
|
||||||
|
|
||||||
|
### Code Structure
|
||||||
|
- src/: ${data.codeStructure.files.length} files
|
||||||
|
- lib/: (if exists)
|
||||||
|
|
||||||
|
### Documentation
|
||||||
|
- docs/: ${data.documentation.files.length} files
|
||||||
|
|
||||||
|
### Configuration
|
||||||
|
- Config files: ${data.configuration.files.length} files
|
||||||
|
|
||||||
|
### Tests
|
||||||
|
- tests/: ${data.tests.files.length} files
|
||||||
|
|
||||||
|
### Scripts
|
||||||
|
- scripts/: ${data.scripts.files.length} files
|
||||||
|
`;
|
||||||
|
|
||||||
|
return {
|
||||||
|
markdown,
|
||||||
|
json: data,
|
||||||
|
totalFiles,
|
||||||
|
quality: 90
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Auto-execution check
|
||||||
|
* Runs on PM Mode session start if index is stale
|
||||||
|
*/
|
||||||
|
export async function autoIndex(): Promise<void> {
|
||||||
|
const indexPath = join(process.cwd(), 'PROJECT_INDEX.md');
|
||||||
|
|
||||||
|
if (!isIndexFresh(process.cwd())) {
|
||||||
|
console.log("🔄 Creating repository index (stale or missing)...");
|
||||||
|
await createIndex();
|
||||||
|
} else {
|
||||||
|
console.log("✅ Repository index is fresh");
|
||||||
|
}
|
||||||
|
}
|
||||||
14
index/package.json
Normal file
14
index/package.json
Normal file
@@ -0,0 +1,14 @@
|
|||||||
|
{
|
||||||
|
"name": "@pm-agent/index",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"description": "Repository structure index for fast context loading (94% token reduction)",
|
||||||
|
"main": "index.ts",
|
||||||
|
"scripts": {
|
||||||
|
"test": "jest"
|
||||||
|
},
|
||||||
|
"dependencies": {},
|
||||||
|
"devDependencies": {
|
||||||
|
"@types/node": "^20.0.0",
|
||||||
|
"typescript": "^5.0.0"
|
||||||
|
}
|
||||||
|
}
|
||||||
171
pm/confidence.ts
Normal file
171
pm/confidence.ts
Normal file
@@ -0,0 +1,171 @@
|
|||||||
|
/**
|
||||||
|
* Confidence Check - Pre-implementation confidence assessment
|
||||||
|
*
|
||||||
|
* Prevents wrong-direction execution by assessing confidence BEFORE starting.
|
||||||
|
* Requires ≥90% confidence to proceed with implementation.
|
||||||
|
*
|
||||||
|
* Test Results (2025-10-21):
|
||||||
|
* - Precision: 1.000 (no false positives)
|
||||||
|
* - Recall: 1.000 (no false negatives)
|
||||||
|
* - 8/8 test cases passed
|
||||||
|
*/
|
||||||
|
|
||||||
|
export interface Context {
|
||||||
|
task?: string;
|
||||||
|
duplicate_check_complete?: boolean;
|
||||||
|
architecture_check_complete?: boolean;
|
||||||
|
official_docs_verified?: boolean;
|
||||||
|
oss_reference_complete?: boolean;
|
||||||
|
root_cause_identified?: boolean;
|
||||||
|
confidence_checks?: string[];
|
||||||
|
[key: string]: any;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Assess confidence level (0.0 - 1.0)
|
||||||
|
*
|
||||||
|
* Investigation Phase Checks:
|
||||||
|
* 1. No duplicate implementations? (25%)
|
||||||
|
* 2. Architecture compliance? (25%)
|
||||||
|
* 3. Official documentation verified? (20%)
|
||||||
|
* 4. Working OSS implementations referenced? (15%)
|
||||||
|
* 5. Root cause identified? (15%)
|
||||||
|
*
|
||||||
|
* @param context - Task context with investigation flags
|
||||||
|
* @returns Confidence score (0.0 = no confidence, 1.0 = absolute certainty)
|
||||||
|
*/
|
||||||
|
export async function confidenceCheck(context: Context): Promise<number> {
|
||||||
|
let score = 0.0;
|
||||||
|
const checks: string[] = [];
|
||||||
|
|
||||||
|
// Check 1: No duplicate implementations (25%)
|
||||||
|
if (noDuplicates(context)) {
|
||||||
|
score += 0.25;
|
||||||
|
checks.push("✅ No duplicate implementations found");
|
||||||
|
} else {
|
||||||
|
checks.push("❌ Check for existing implementations first");
|
||||||
|
}
|
||||||
|
|
||||||
|
// Check 2: Architecture compliance (25%)
|
||||||
|
if (architectureCompliant(context)) {
|
||||||
|
score += 0.25;
|
||||||
|
checks.push("✅ Uses existing tech stack (e.g., Supabase)");
|
||||||
|
} else {
|
||||||
|
checks.push("❌ Verify architecture compliance (avoid reinventing)");
|
||||||
|
}
|
||||||
|
|
||||||
|
// Check 3: Official documentation verified (20%)
|
||||||
|
if (hasOfficialDocs(context)) {
|
||||||
|
score += 0.2;
|
||||||
|
checks.push("✅ Official documentation verified");
|
||||||
|
} else {
|
||||||
|
checks.push("❌ Read official docs first");
|
||||||
|
}
|
||||||
|
|
||||||
|
// Check 4: Working OSS implementations referenced (15%)
|
||||||
|
if (hasOssReference(context)) {
|
||||||
|
score += 0.15;
|
||||||
|
checks.push("✅ Working OSS implementation found");
|
||||||
|
} else {
|
||||||
|
checks.push("❌ Search for OSS implementations");
|
||||||
|
}
|
||||||
|
|
||||||
|
// Check 5: Root cause identified (15%)
|
||||||
|
if (rootCauseIdentified(context)) {
|
||||||
|
score += 0.15;
|
||||||
|
checks.push("✅ Root cause identified");
|
||||||
|
} else {
|
||||||
|
checks.push("❌ Continue investigation to identify root cause");
|
||||||
|
}
|
||||||
|
|
||||||
|
// Store check results
|
||||||
|
context.confidence_checks = checks;
|
||||||
|
|
||||||
|
// Display checks
|
||||||
|
console.log("📋 Confidence Checks:");
|
||||||
|
checks.forEach(check => console.log(` ${check}`));
|
||||||
|
console.log("");
|
||||||
|
|
||||||
|
return score;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Check for duplicate implementations
|
||||||
|
*
|
||||||
|
* Before implementing, verify:
|
||||||
|
* - No existing similar functions/modules (Glob/Grep)
|
||||||
|
* - No helper functions that solve the same problem
|
||||||
|
* - No libraries that provide this functionality
|
||||||
|
*/
|
||||||
|
function noDuplicates(context: Context): boolean {
|
||||||
|
return context.duplicate_check_complete ?? false;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Check architecture compliance
|
||||||
|
*
|
||||||
|
* Verify solution uses existing tech stack:
|
||||||
|
* - Supabase project → Use Supabase APIs (not custom API)
|
||||||
|
* - Next.js project → Use Next.js patterns (not custom routing)
|
||||||
|
* - Turborepo → Use workspace patterns (not manual scripts)
|
||||||
|
*/
|
||||||
|
function architectureCompliant(context: Context): boolean {
|
||||||
|
return context.architecture_check_complete ?? false;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Check if official documentation verified
|
||||||
|
*
|
||||||
|
* For testing: uses context flag 'official_docs_verified'
|
||||||
|
* For production: checks for README.md, CLAUDE.md, docs/ directory
|
||||||
|
*/
|
||||||
|
function hasOfficialDocs(context: Context): boolean {
|
||||||
|
// Check context flag (for testing and runtime)
|
||||||
|
if ('official_docs_verified' in context) {
|
||||||
|
return context.official_docs_verified ?? false;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Fallback: check for documentation files (production)
|
||||||
|
// This would require filesystem access in Node.js
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Check if working OSS implementations referenced
|
||||||
|
*
|
||||||
|
* Search for:
|
||||||
|
* - Similar open-source solutions
|
||||||
|
* - Reference implementations in popular projects
|
||||||
|
* - Community best practices
|
||||||
|
*/
|
||||||
|
function hasOssReference(context: Context): boolean {
|
||||||
|
return context.oss_reference_complete ?? false;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Check if root cause is identified with high certainty
|
||||||
|
*
|
||||||
|
* Verify:
|
||||||
|
* - Problem source pinpointed (not guessing)
|
||||||
|
* - Solution addresses root cause (not symptoms)
|
||||||
|
* - Fix verified against official docs/OSS patterns
|
||||||
|
*/
|
||||||
|
function rootCauseIdentified(context: Context): boolean {
|
||||||
|
return context.root_cause_identified ?? false;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Get recommended action based on confidence level
|
||||||
|
*
|
||||||
|
* @param confidence - Confidence score (0.0 - 1.0)
|
||||||
|
* @returns Recommended action
|
||||||
|
*/
|
||||||
|
export function getRecommendation(confidence: number): string {
|
||||||
|
if (confidence >= 0.9) {
|
||||||
|
return "✅ High confidence (≥90%) - Proceed with implementation";
|
||||||
|
} else if (confidence >= 0.7) {
|
||||||
|
return "⚠️ Medium confidence (70-89%) - Continue investigation, DO NOT implement yet";
|
||||||
|
} else {
|
||||||
|
return "❌ Low confidence (<70%) - STOP and continue investigation loop";
|
||||||
|
}
|
||||||
|
}
|
||||||
159
pm/index.ts
Normal file
159
pm/index.ts
Normal file
@@ -0,0 +1,159 @@
|
|||||||
|
/**
|
||||||
|
* PM Agent - Project Manager with Confidence-Driven Workflow
|
||||||
|
*
|
||||||
|
* Auto-executes on session start via hooks/hooks.json
|
||||||
|
* Orchestrates sub-agents with 90% confidence threshold
|
||||||
|
*/
|
||||||
|
|
||||||
|
import { execSync } from 'child_process';
|
||||||
|
import { confidenceCheck } from './confidence';
|
||||||
|
|
||||||
|
interface SessionContext {
|
||||||
|
gitStatus: string;
|
||||||
|
tokenBudget: number;
|
||||||
|
projectRoot: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Session Start Protocol
|
||||||
|
* Auto-executes when Claude Code starts
|
||||||
|
*/
|
||||||
|
export async function sessionStart(): Promise<void> {
|
||||||
|
console.log("🚀 PM Agent activated");
|
||||||
|
|
||||||
|
// 1. Check git status
|
||||||
|
const gitStatus = checkGitStatus();
|
||||||
|
console.log(`📊 Git: ${gitStatus}`);
|
||||||
|
|
||||||
|
// 2. Token budget check (from Claude Code UI)
|
||||||
|
console.log("💡 Check token budget with /context");
|
||||||
|
|
||||||
|
// 3. Ready
|
||||||
|
console.log("✅ PM Agent ready to accept tasks");
|
||||||
|
console.log("");
|
||||||
|
console.log("**Core Capabilities**:");
|
||||||
|
console.log("- 🔍 Pre-implementation confidence check (≥90% required)");
|
||||||
|
console.log("- ⚡ Parallel investigation and execution");
|
||||||
|
console.log("- 📊 Token-budget-aware operations");
|
||||||
|
console.log("");
|
||||||
|
console.log("**Usage**: Assign tasks directly - PM Agent will orchestrate");
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Check git repository status
|
||||||
|
*/
|
||||||
|
function checkGitStatus(): string {
|
||||||
|
try {
|
||||||
|
const status = execSync('git status --porcelain', { encoding: 'utf-8' });
|
||||||
|
if (!status.trim()) {
|
||||||
|
return 'clean';
|
||||||
|
}
|
||||||
|
const lines = status.trim().split('\n').length;
|
||||||
|
return `${lines} file(s) modified`;
|
||||||
|
} catch {
|
||||||
|
return 'not a git repo';
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Main task handler
|
||||||
|
* Called when user assigns a task
|
||||||
|
*/
|
||||||
|
export async function handleTask(task: string): Promise<void> {
|
||||||
|
console.log(`📝 Task received: ${task}`);
|
||||||
|
console.log("");
|
||||||
|
|
||||||
|
// Start confidence-driven workflow
|
||||||
|
await confidenceDrivenWorkflow(task);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Confidence-Driven Workflow
|
||||||
|
*
|
||||||
|
* 1. Investigation phase (loop until 90% confident)
|
||||||
|
* 2. Confidence check
|
||||||
|
* 3. Implementation (only when ≥90%)
|
||||||
|
*/
|
||||||
|
async function confidenceDrivenWorkflow(task: string): Promise<void> {
|
||||||
|
let confidence = 0;
|
||||||
|
let iteration = 0;
|
||||||
|
const MAX_ITERATIONS = 10;
|
||||||
|
|
||||||
|
console.log("🔍 Starting investigation phase...");
|
||||||
|
console.log("");
|
||||||
|
|
||||||
|
while (confidence < 0.9 && iteration < MAX_ITERATIONS) {
|
||||||
|
iteration++;
|
||||||
|
console.log(`🔄 Investigation iteration ${iteration}...`);
|
||||||
|
|
||||||
|
// Investigation actions (delegated to sub-agents)
|
||||||
|
const context = await investigate(task);
|
||||||
|
|
||||||
|
// Self-evaluate confidence
|
||||||
|
confidence = await confidenceCheck(context);
|
||||||
|
|
||||||
|
console.log(`📊 Confidence: ${(confidence * 100).toFixed(0)}%`);
|
||||||
|
|
||||||
|
if (confidence < 0.9) {
|
||||||
|
console.log("⚠️ Confidence < 90% - Continue investigation");
|
||||||
|
console.log("");
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
if (confidence >= 0.9) {
|
||||||
|
console.log("✅ High confidence (≥90%) - Proceeding to implementation");
|
||||||
|
console.log("");
|
||||||
|
// Implementation phase
|
||||||
|
await implement(task);
|
||||||
|
} else {
|
||||||
|
console.log("❌ Max iterations reached - Request user clarification");
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Investigation phase
|
||||||
|
* Delegates to sub-agents: research, index, grep, etc.
|
||||||
|
*/
|
||||||
|
async function investigate(task: string): Promise<any> {
|
||||||
|
// This will be orchestrated by Claude using:
|
||||||
|
// - /research for web research
|
||||||
|
// - /index-repo for codebase structure
|
||||||
|
// - Glob/Grep for code search
|
||||||
|
// - WebFetch for official docs
|
||||||
|
|
||||||
|
return {
|
||||||
|
task,
|
||||||
|
duplicate_check_complete: false,
|
||||||
|
architecture_check_complete: false,
|
||||||
|
official_docs_verified: false,
|
||||||
|
oss_reference_complete: false,
|
||||||
|
root_cause_identified: false
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Implementation phase
|
||||||
|
* Only executed when confidence ≥ 90%
|
||||||
|
*/
|
||||||
|
async function implement(task: string): Promise<void> {
|
||||||
|
console.log(`🚀 Implementing: ${task}`);
|
||||||
|
// Actual implementation delegated to Claude
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Memory Management (Mindbase MCP integration)
|
||||||
|
* Zero-footprint: No auto-load, explicit load/save only
|
||||||
|
*/
|
||||||
|
export const memory = {
|
||||||
|
load: async () => {
|
||||||
|
console.log("💾 Use /sc:load to load context from Mindbase MCP");
|
||||||
|
},
|
||||||
|
save: async () => {
|
||||||
|
console.log("💾 Use /sc:save to persist session to Mindbase MCP");
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
// Auto-execute on session start
|
||||||
|
if (require.main === module) {
|
||||||
|
sessionStart();
|
||||||
|
}
|
||||||
18
pm/package.json
Normal file
18
pm/package.json
Normal file
@@ -0,0 +1,18 @@
|
|||||||
|
{
|
||||||
|
"name": "@pm-agent/core",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"description": "PM Agent - Project Manager with 90% confidence checks",
|
||||||
|
"main": "index.ts",
|
||||||
|
"scripts": {
|
||||||
|
"test": "jest",
|
||||||
|
"build": "tsc"
|
||||||
|
},
|
||||||
|
"dependencies": {},
|
||||||
|
"devDependencies": {
|
||||||
|
"@types/node": "^20.0.0",
|
||||||
|
"typescript": "^5.0.0"
|
||||||
|
},
|
||||||
|
"engines": {
|
||||||
|
"node": ">=18.0.0"
|
||||||
|
}
|
||||||
|
}
|
||||||
207
research/index.ts
Normal file
207
research/index.ts
Normal file
@@ -0,0 +1,207 @@
|
|||||||
|
/**
|
||||||
|
* Research Agent - Deep web research with adaptive planning
|
||||||
|
*
|
||||||
|
* Features:
|
||||||
|
* - Adaptive depth control (quick, standard, deep, exhaustive)
|
||||||
|
* - Parallel-first search execution
|
||||||
|
* - Multi-hop exploration
|
||||||
|
* - Evidence-based synthesis
|
||||||
|
*
|
||||||
|
* MCP Integration:
|
||||||
|
* - Tavily: Primary search and extraction
|
||||||
|
* - Sequential: Complex reasoning
|
||||||
|
* - Playwright: JavaScript-heavy content
|
||||||
|
* - Serena: Session persistence
|
||||||
|
*/
|
||||||
|
|
||||||
|
export interface ResearchOptions {
|
||||||
|
query: string;
|
||||||
|
depth?: 'quick' | 'standard' | 'deep' | 'exhaustive';
|
||||||
|
strategy?: 'planning' | 'intent' | 'unified';
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface ResearchResult {
|
||||||
|
summary: string;
|
||||||
|
sources: Source[];
|
||||||
|
confidence: number;
|
||||||
|
timestamp: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
interface Source {
|
||||||
|
url: string;
|
||||||
|
title: string;
|
||||||
|
excerpt: string;
|
||||||
|
credibility: number;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Execute deep research
|
||||||
|
*
|
||||||
|
* Flow:
|
||||||
|
* 1. Understand (5-10% effort)
|
||||||
|
* 2. Plan (10-15% effort)
|
||||||
|
* 3. TodoWrite (5% effort)
|
||||||
|
* 4. Execute (50-60% effort)
|
||||||
|
* 5. Track (Continuous)
|
||||||
|
* 6. Validate (10-15% effort)
|
||||||
|
*
|
||||||
|
* @param options - Research configuration
|
||||||
|
* @returns Research results with sources
|
||||||
|
*/
|
||||||
|
export async function research(options: ResearchOptions): Promise<ResearchResult> {
|
||||||
|
const { query, depth = 'standard', strategy = 'unified' } = options;
|
||||||
|
|
||||||
|
console.log(`🔍 Starting ${depth} research: ${query}`);
|
||||||
|
console.log(`📊 Strategy: ${strategy}`);
|
||||||
|
console.log("");
|
||||||
|
|
||||||
|
// 1. Understand (5-10% effort)
|
||||||
|
const context = await understand(query);
|
||||||
|
console.log(`✅ Understanding complete (complexity: ${context.complexity})`);
|
||||||
|
|
||||||
|
// 2. Plan (10-15% effort)
|
||||||
|
const plan = await createPlan(context, depth, strategy);
|
||||||
|
console.log(`✅ Research plan created (${plan.tasks.length} tasks)`);
|
||||||
|
|
||||||
|
// 3. TodoWrite (5% effort)
|
||||||
|
console.log(`📝 Creating task list...`);
|
||||||
|
// TodoWrite integration would go here
|
||||||
|
|
||||||
|
// 4. Execute (50-60% effort)
|
||||||
|
console.log(`🚀 Executing research...`);
|
||||||
|
const results = await execute(plan);
|
||||||
|
|
||||||
|
// 5. Validate (10-15% effort)
|
||||||
|
console.log(`🔍 Validating results...`);
|
||||||
|
const validated = await validate(results);
|
||||||
|
|
||||||
|
// 6. Generate report
|
||||||
|
const report = await generateReport(validated, query, depth);
|
||||||
|
|
||||||
|
return report;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Phase 1: Understand query
|
||||||
|
*/
|
||||||
|
async function understand(query: string): Promise<any> {
|
||||||
|
return {
|
||||||
|
query,
|
||||||
|
complexity: assessComplexity(query),
|
||||||
|
requiredInformation: identifyRequirements(query),
|
||||||
|
resourceNeeds: 'web_search',
|
||||||
|
successCriteria: ['evidence', 'credibility', 'completeness']
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
function assessComplexity(query: string): 'simple' | 'moderate' | 'complex' {
|
||||||
|
// Heuristic: word count, question type, etc.
|
||||||
|
if (query.length < 50) return 'simple';
|
||||||
|
if (query.length < 150) return 'moderate';
|
||||||
|
return 'complex';
|
||||||
|
}
|
||||||
|
|
||||||
|
function identifyRequirements(query: string): string[] {
|
||||||
|
// Identify what type of information is needed
|
||||||
|
return ['facts', 'sources', 'analysis'];
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Phase 2: Create research plan
|
||||||
|
*/
|
||||||
|
async function createPlan(context: any, depth: string, strategy: string): Promise<any> {
|
||||||
|
const hops = getHopCount(depth);
|
||||||
|
|
||||||
|
return {
|
||||||
|
strategy,
|
||||||
|
tasks: generateTasks(context, hops),
|
||||||
|
parallelizationPlan: identifyParallelTasks(context),
|
||||||
|
milestones: createMilestones(hops)
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
function getHopCount(depth: string): number {
|
||||||
|
const hopMap = {
|
||||||
|
'quick': 1,
|
||||||
|
'standard': 2-3,
|
||||||
|
'deep': 3-4,
|
||||||
|
'exhaustive': 5
|
||||||
|
};
|
||||||
|
return hopMap[depth] || 2;
|
||||||
|
}
|
||||||
|
|
||||||
|
function generateTasks(context: any, hops: number): any[] {
|
||||||
|
// Generate research tasks based on context and depth
|
||||||
|
return [];
|
||||||
|
}
|
||||||
|
|
||||||
|
function identifyParallelTasks(context: any): any[] {
|
||||||
|
// Identify which searches can run in parallel
|
||||||
|
return [];
|
||||||
|
}
|
||||||
|
|
||||||
|
function createMilestones(hops: number): string[] {
|
||||||
|
return [`Complete hop ${hop}` for (let hop = 1; hop <= hops; hop++)];
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Phase 4: Execute research
|
||||||
|
*/
|
||||||
|
async function execute(plan: any): Promise<any> {
|
||||||
|
// Execute searches (parallel-first approach)
|
||||||
|
// This would integrate with Tavily MCP, WebSearch, etc.
|
||||||
|
|
||||||
|
return {
|
||||||
|
findings: [],
|
||||||
|
sources: [],
|
||||||
|
confidence: 0.8
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Phase 5: Validate results
|
||||||
|
*/
|
||||||
|
async function validate(results: any): Promise<any> {
|
||||||
|
// Verify evidence chains
|
||||||
|
// Check source credibility
|
||||||
|
// Resolve contradictions
|
||||||
|
// Ensure completeness
|
||||||
|
|
||||||
|
return {
|
||||||
|
...results,
|
||||||
|
validated: true,
|
||||||
|
contradictions: [],
|
||||||
|
gaps: []
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Phase 6: Generate report
|
||||||
|
*/
|
||||||
|
async function generateReport(data: any, query: string, depth: string): Promise<ResearchResult> {
|
||||||
|
const timestamp = new Date().toISOString();
|
||||||
|
const filename = `docs/research/${slugify(query)}_${timestamp.split('T')[0]}.md`;
|
||||||
|
|
||||||
|
console.log(`💾 Saving report to: ${filename}`);
|
||||||
|
|
||||||
|
return {
|
||||||
|
summary: `Research on: ${query}`,
|
||||||
|
sources: data.sources || [],
|
||||||
|
confidence: data.confidence || 0.8,
|
||||||
|
timestamp
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
function slugify(text: string): string {
|
||||||
|
return text.toLowerCase().replace(/[^a-z0-9]+/g, '_');
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Adaptive depth examples
|
||||||
|
*/
|
||||||
|
export const examples = {
|
||||||
|
quick: "/research 'latest quantum computing news' --depth quick",
|
||||||
|
standard: "/research 'competitive analysis of AI coding assistants'",
|
||||||
|
deep: "/research 'distributed systems best practices' --depth deep",
|
||||||
|
exhaustive: "/research 'self-improving AI agents' --depth exhaustive"
|
||||||
|
};
|
||||||
14
research/package.json
Normal file
14
research/package.json
Normal file
@@ -0,0 +1,14 @@
|
|||||||
|
{
|
||||||
|
"name": "@pm-agent/research",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"description": "Deep web research with adaptive planning and intelligent search",
|
||||||
|
"main": "index.ts",
|
||||||
|
"scripts": {
|
||||||
|
"test": "jest"
|
||||||
|
},
|
||||||
|
"dependencies": {},
|
||||||
|
"devDependencies": {
|
||||||
|
"@types/node": "^20.0.0",
|
||||||
|
"typescript": "^5.0.0"
|
||||||
|
}
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user