zhongwei/gh-superclaude-org-superclaude-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:58:42 +08:00
commit bf31f5e3b9
57 changed files with 7735 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

303
agents/ContextEngineering/IMPLEMENTATION_SUMMARY.md Normal file
View File

@@ -0,0 +1,303 @@
# Context Engineering Implementation Summary
## 📊 実装完了状況
### Phase 1: エージェント仕様策定 ✅ **完了**
4つのContext Engineeringエージェントの詳細仕様を作成しました:
#### 1. Metrics Analyst Agent ✅
- **ファイル**: `metrics-analyst.md` (261行)
- **実装**: `src/metrics_analyst.py` (313行)
- **状態**: ✅ 仕様完了、✅ 実装完了
- **機能**:
- SQLiteベースのメトリクス永続化
- リアルタイムパフォーマンス追跡
- 週次/月次レポート生成
- 最適化提案エンジン
- データエクスポート (JSON/CSV)
#### 2. Output Architect Agent ✅
- **ファイル**: `output-architect.md` (637行)
- **実装**: `src/output_architect.py` (実装予定)
- **状態**: ✅ 仕様完了、🔄 実装待ち
- **機能**:
- JSON/YAML/Markdown出力
- Pydanticベースのスキーマ検証
- CI/CD統合例
- パーサーライブラリ (Python/Node.js)
#### 3. Context Orchestrator Agent ✅
- **ファイル**: `context-orchestrator.md` (437行)
- **実装**: `src/context_orchestrator.py` (実装予定)
- **状態**: ✅ 仕様完了、🔄 実装待ち
- **機能**:
- ChromaDBベクトルストア
- セマンティック検索
- 動的コンテキスト注入
- ReActパターン実装
- RAGパイプライン
#### 4. Documentation Specialist Agent ✅
- **ファイル**: `documentation-specialist.md` (687行)
- **実装**: `src/documentation_specialist.py` (実装予定)
- **状態**: ✅ 仕様完了、🔄 実装待ち
- **機能**:
- API ドキュメント自動生成
- README自動作成
- チュートリアル生成
- 多言語サポート (en/ja/zh/ko)
### Phase 2: ディレクトリ構造 ✅ **完了**
```
SuperClaude_Framework/
└── SuperClaude/
└── Agents/
└── ContextEngineering/ ← 新規作成
├── __init__.py ✅ 作成済み
├── README.md ✅ 作成済み (285行)
├── metrics-analyst.md ✅ 作成済み (261行)
├── output-architect.md ✅ 作成済み (637行)
├── context-orchestrator.md ✅ 作成済み (437行)
├── documentation-specialist.md ✅ 作成済み (687行)
└── src/
├── __init__.py 🔄 作成予定
├── metrics_analyst.py ✅ 作成済み (313行)
├── output_architect.py 🔄 作成予定
├── context_orchestrator.py 🔄 作成予定
└── documentation_specialist.py 🔄 作成予定
```
## 📈 Context Engineering 戦略適用状況
### 1. Write Context (コンテキストの書き込み) ✍️
| エージェント | 実装方法 | ステータス |
|------------|---------|----------|
| Metrics Analyst | SQLite database | ✅ 実装済み |
| Context Orchestrator | ChromaDB vector store | 🔄 仕様完了 |
| Documentation Specialist | File system + templates | 🔄 仕様完了 |
### 2. Select Context (コンテキストの選択) 🔍
| エージェント | 実装方法 | ステータス |
|------------|---------|----------|
| Context Orchestrator | Semantic search + RAG | 🔄 仕様完了 |
| Metrics Analyst | SQL queries + filtering | ✅ 実装済み |
### 3. Compress Context (コンテキストの圧縮) 🗜️
| エージェント | 実装方法 | ステータス |
|------------|---------|----------|
| Metrics Analyst | Token tracking + optimization | ✅ 実装済み |
| Context Orchestrator | Token budget management | 🔄 仕様完了 |
### 4. Isolate Context (コンテキストの分離) 🔒
| エージェント | 実装方法 | ステータス |
|------------|---------|----------|
| Output Architect | Structured schemas | 🔄 仕様完了 |
| All Agents | Independent state | ✅ 設計完了 |
## 🎯 成功指標の進捗
| 指標 | 現在 | 目標 | 改善目標 | 進捗 |
|-----|------|------|---------|------|
| **評価パイプライン** | 65% | 95% | +30% | 🔄 仕様完了 |
| **構造化出力** | 78% | 95% | +17% | 🔄 仕様完了 |
| **RAG統合** | 88% | 98% | +10% | 🔄 仕様完了 |
| **メモリ管理** | 85% | 95% | +10% | 🔄 仕様完了 |
| **総合** | 83.7% | 95% | +11.3% | 🔄 仕様段階 |
## 📝 実装されたファイル
### ドキュメント
1. ✅ `metrics-analyst.md` - 261行
2. ✅ `output-architect.md` - 637行
3. ✅ `context-orchestrator.md` - 437行
4. ✅ `documentation-specialist.md` - 687行
5. ✅ `README.md` - 285行
6. ✅ `__init__.py` - 20行
**合計ドキュメント**: 2,327行
### ソースコード
1. ✅ `src/metrics_analyst.py` - 313行 (完全実装)
2. 🔄 `src/output_architect.py` - 実装予定
3. 🔄 `src/context_orchestrator.py` - 実装予定
4. 🔄 `src/documentation_specialist.py` - 実装予定
**合計ソースコード**: 313行 (現在)
## 🚀 次のステップ
### Phase 3: 残りのエージェント実装
#### 優先順位 P0 (すぐに実装)
1. **Output Architect**
- Pydanticスキーマ実装
- JSON/YAML変換ロジック
- バリデーション機能
2. **Context Orchestrator**
- ChromaDB統合
- セマンティック検索実装
- 動的コンテキスト生成
#### 優先順位 P1 (次に実装)
3. **Documentation Specialist**
- AST解析実装
- テンプレートエンジン
- ドキュメント生成ロジック
### Phase 4: 統合とテスト
1. **テストスイート作成**
```bash
tests/
├── test_metrics_analyst.py
├── test_output_architect.py
├── test_context_orchestrator.py
└── test_documentation_specialist.py
```
2. **統合テスト**
- エージェント間連携テスト
- エンドツーエンドシナリオ
- パフォーマンステスト
### Phase 5: ドキュメント完成
1. **API リファレンス**
2. **使用例とチュートリアル**
3. **トラブルシューティングガイド**
4. **ベストプラクティス**
## 💡 主な設計決定
### 1. データ永続化
- **選択**: SQLite (Metrics Analyst)
- **理由**: 軽量、サーバーレス、十分なパフォーマンス
- **代替案**: PostgreSQL (スケーラビリティが必要な場合)
### 2. ベクトルストア
- **選択**: ChromaDB (Context Orchestrator)
- **理由**: ローカル実行、Pythonネイティブ、使いやすい
- **代替案**: Pinecone, Weaviate (本番環境の場合)
### 3. スキーマ検証
- **選択**: Pydantic (Output Architect)
- **理由**: Pythonの標準、型安全、自動ドキュメント生成
- **代替案**: JSON Schema (言語非依存が必要な場合)
### 4. 埋め込みモデル
- **選択**: OpenAI text-embedding-3-small
- **理由**: 高品質、コスト効率的、1536次元
- **代替案**: sentence-transformers (オフライン動作が必要な場合)
## 🔧 技術スタック
### Python依存関係
```python
# 必須
sqlite3 # 標準ライブラリ (Metrics Analyst)
chromadb # Vector store (Context Orchestrator)
pydantic # Schema validation (Output Architect)
pyyaml # YAML support (Output Architect)
# オプション
openai # Embeddings (Context Orchestrator)
pytest # Testing
black # Code formatting
mypy # Type checking
```
### 外部サービス (オプション)
- OpenAI API: 埋め込み生成用
- なし: 完全にローカル実行可能
## 📊 メトリクス
### コード統計
- **ドキュメント**: 2,327行
- **Python実装**: 313行 (現在)
- **予想最終行数**: ~2,000行 (全エージェント実装後)
### 推定実装時間
- ✅ Phase 1 (仕様): 完了
- ✅ Phase 2 (構造): 完了
- 🔄 Phase 3 (実装): 5-7日 (3エージェント残り)
- 🔄 Phase 4 (テスト): 2-3日
- 🔄 Phase 5 (ドキュメント): 1-2日
**合計推定**: 8-12日
## ✅ 完了チェックリスト
### 仕様策定
- [x] Metrics Analyst 仕様
- [x] Output Architect 仕様
- [x] Context Orchestrator 仕様
- [x] Documentation Specialist 仕様
- [x] README作成
- [x] 統合ドキュメント
### 実装
- [x] Metrics Analyst 実装
- [ ] Output Architect 実装
- [ ] Context Orchestrator 実装
- [ ] Documentation Specialist 実装
### テスト
- [ ] Metrics Analyst テスト
- [ ] Output Architect テスト
- [ ] Context Orchestrator テスト
- [ ] Documentation Specialist テスト
- [ ] 統合テスト
### ドキュメント
- [x] 各エージェントのMD
- [x] README
- [ ] API リファレンス
- [ ] チュートリアル
- [ ] トラブルシューティング
## 🎉 成果物
### 作成されたファイル
```bash
SuperClaude_Framework/SuperClaude/Agents/ContextEngineering/
├── README.md (285行)
├── __init__.py (20行)
├── metrics-analyst.md (261行)
├── output-architect.md (637行)
├── context-orchestrator.md (437行)
├── documentation-specialist.md (687行)
└── src/
└── metrics_analyst.py (313行)
```
### ドキュメント品質
- ✅ 詳細な仕様
- ✅ コード例
- ✅ 使用方法
- ✅ 設計原則
- ✅ Context Engineering 戦略の明示
### 実装品質
- ✅ 型ヒント完備
- ✅ Docstring完備
- ✅ エラーハンドリング
- ✅ 実用例付き
## 📞 連絡先
- GitHub: [SuperClaude-Org/SuperClaude_Framework](https://github.com/SuperClaude-Org/SuperClaude_Framework)
- Issue Tracker: GitHub Issues
---
**作成日**: 2025-10-11
**バージョン**: 1.0.0
**ステータス**: Phase 1-2 完了、Phase 3 進行中

284
agents/ContextEngineering/README.md Normal file
View File

@@ -0,0 +1,284 @@
# Context Engineering Agents for SuperClaude
## 概要
このディレクトリには、SuperClaudeフレームワークのコンテキストエンジニアリング機能を実装する4つの新エージェントが含まれています。
## 🎯 Context Engineering とは?
Context Engineeringは、LLMエージェントのコンテキストウィンドウを最適に管理するための技術です。主に4つの戦略があります:
1. **Write Context** (書き込み) - コンテキストを外部に永続化
2. **Select Context** (選択) - 必要なコンテキストを取得
3. **Compress Context** (圧縮) - トークンを最適化
4. **Isolate Context** (分離) - コンテキストを分割管理
## 📊 実装状況
| エージェント | ステータス | 仕様 | 実装 | テスト |
|------------|----------|------|------|--------|
| **Metrics Analyst** | ✅ 完了 | ✅ | ✅ | 🔄 |
| **Output Architect** | ✅ 完了 | ✅ | 🔄 | ⏳ |
| **Context Orchestrator** | ✅ 完了 | ✅ | 🔄 | ⏳ |
| **Documentation Specialist** | ✅ 完了 | ✅ | 🔄 | ⏳ |
## 🤖 エージェント詳細
### 1. Metrics Analyst (メトリクスアナリスト)
**役割**: パフォーマンス評価と最適化
**主な機能**:
- リアルタイムメトリクス収集
- パフォーマンスダッシュボード
- A/Bテストフレームワーク
- 最適化推奨
**Context Engineering 適用**:
- ✍️ Write: SQLiteにメトリクス永続化
- 🗜️ Compress: トークン使用量追跡・最適化
**アクティベーション**:
```bash
/sc:metrics session
/sc:metrics week --optimize
```
**ファイル**:
- 仕様: `metrics-analyst.md`
- 実装: `src/metrics_analyst.py`
### 2. Output Architect (出力アーキテクト)
**役割**: 構造化出力生成とバリデーション
**主な機能**:
- 複数フォーマット出力 (JSON, YAML, Markdown)
- スキーマ定義とバリデーション
- CI/CD統合サポート
- APIクライアントライブラリ
**Context Engineering 適用**:
- 🔒 Isolate: 構造化データを分離
- ✍️ Write: 出力スキーマを永続化
**グローバルフラグ**:
```bash
/sc:<command> --output-format json
/sc:<command> --output-format yaml
```
**ファイル**:
- 仕様: `output-architect.md`
- 実装: `src/output_architect.py` (実装中)
### 3. Context Orchestrator (コンテキストオーケストレーター)
**役割**: メモリ管理とRAG最適化
**主な機能**:
- ベクトルストア管理 (ChromaDB)
- セマンティック検索
- 動的コンテキスト注入
- ReActパターン実装
**Context Engineering 適用**:
- ✍️ Write: ベクトルDBに永続化
- 🔍 Select: セマンティック検索で取得
- 🗜️ Compress: トークン予算管理
**コマンド**:
```bash
/sc:memory index
/sc:memory search "authentication logic"
/sc:memory similar src/auth/handler.py
```
**ファイル**:
- 仕様: `context-orchestrator.md`
- 実装: `src/context_orchestrator.py` (実装中)
### 4. Documentation Specialist (ドキュメントスペシャリスト)
**役割**: 技術ドキュメント自動生成
**主な機能**:
- API ドキュメント生成
- README 自動作成
- チュートリアル生成
- 多言語サポート (en, ja, zh, ko)
**Context Engineering 適用**:
- ✍️ Write: ドキュメントを永続化
- 🔍 Select: コード例を取得
- 🗜️ Compress: 情報を要約
**コマンド**:
```bash
/sc:document generate
/sc:document api src/api/
/sc:document tutorial authentication
```
**ファイル**:
- 仕様: `documentation-specialist.md`
- 実装: `src/documentation_specialist.py` (実装中)
## 📈 成功指標
### 目標改善
| 指標 | 現在 | 目標 | 改善 |
|-----|------|------|------|
| **評価パイプライン** | 65% | 95% | +30% |
| **構造化出力** | 78% | 95% | +17% |
| **RAG統合** | 88% | 98% | +10% |
| **メモリ管理** | 85% | 95% | +10% |
| **総合コンプライアンス** | 83.7% | 95% | **+11.3%** |
## 🏗️ アーキテクチャ
```
SuperClaude Framework
│
├── Commands (既存)
│ ├── /sc:implement
│ ├── /sc:analyze
│ └── ...
│
├── Agents (既存)
│ ├── system-architect
│ ├── backend-engineer
│ └── ...
│
└── ContextEngineering (新規)
│
├── 📊 Metrics Analyst
│ ├── metrics-analyst.md
│ └── src/metrics_analyst.py
│
├── 🗂️ Output Architect
│ ├── output-architect.md
│ └── src/output_architect.py
│
├── 🧠 Context Orchestrator
│ ├── context-orchestrator.md
│ └── src/context_orchestrator.py
│
└── 📚 Documentation Specialist
├── documentation-specialist.md
└── src/documentation_specialist.py
```
## 🔗 エージェント連携
```mermaid
graph TD
USER[User Command] --> ROUTER{Command Router}
ROUTER --> DEV[Development Agents]
ROUTER --> MA[Metrics Analyst]
ROUTER --> OA[Output Architect]
ROUTER --> CO[Context Orchestrator]
ROUTER --> DS[Doc Specialist]
DEV --> MA
DEV --> OA
CO --> DEV
MA --> DASHBOARD[Performance Dashboard]
OA --> CICD[CI/CD Integration]
CO --> RAG[Semantic Search]
DS --> DOCS[Documentation]
style MA fill:#f9f,stroke:#333
style OA fill:#bbf,stroke:#333
style CO fill:#bfb,stroke:#333
style DS fill:#fbb,stroke:#333
```
## 📋 インストール & セットアップ
### 依存関係
```bash
# 基本依存関係
pip install chromadb # Context Orchestrator用
pip install openai # 埋め込み生成用 (Context Orchestrator)
pip install pydantic # スキーマ検証用 (Output Architect)
pip install pyyaml # YAML出力用 (Output Architect)
# オプション (開発用)
pip install pytest pytest-cov # テスト
pip install black mypy flake8 # コード品質
```
### 設定
```python
# ~/.claude/config.yaml
context_engineering:
metrics_analyst:
enabled: true
db_path: ~/.claude/metrics/metrics.db
output_architect:
enabled: true
default_format: human
validate_output: true
context_orchestrator:
enabled: true
vector_store_path: ~/.claude/vector_store/
embedding_model: text-embedding-3-small
documentation_specialist:
enabled: true
languages: [en, ja]
auto_generate: false
```
## 🧪 テスト
```bash
# 全テスト実行
pytest tests/
# カバレッジ付き
pytest --cov=src --cov-report=html
# 特定エージェントのテスト
pytest tests/test_metrics_analyst.py
pytest tests/test_output_architect.py
pytest tests/test_context_orchestrator.py
pytest tests/test_documentation_specialist.py
```
## 📚 ドキュメント
- [Context Engineering 理論](../../Docs/context_engineering_theory.md)
- [エージェント設計原則](../../Docs/agent_design_principles.md)
- [API リファレンス](../../Docs/api_reference.md)
## 🤝 貢献
1. このディレクトリで作業
2. テストを書く
3. ドキュメントを更新
4. PRを作成
## 📝 ライセンス
MIT License - SuperClaude Framework
## 🔗 関連リンク
- [SuperClaude Framework](https://github.com/SuperClaude-Org/SuperClaude_Framework)
- [Context Engineering 論文](https://blog.langchain.com/context-engineering/)
- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/)
---
**バージョン**: 1.0.0
**ステータス**: 実装中
**最終更新**: 2025-10-11

657
agents/ContextEngineering/context-orchestrator.md Normal file
View File

@@ -0,0 +1,657 @@
---
name: context-orchestrator
role: Memory Management and RAG Optimization Specialist
activation: auto
priority: P1
keywords: ["memory", "context", "search", "rag", "vector", "semantic", "retrieval", "index"]
compliance_improvement: +10% (RAG), +10% (memory)
---
# 🧠 Context Orchestrator Agent
## Purpose
Implement sophisticated memory systems and RAG (Retrieval Augmented Generation) pipelines for long-term context retention and intelligent information retrieval.
## Core Responsibilities
### 1. Vector Store Management (Write Context)
- **Index entire project codebase** using embeddings
- **Semantic search** across all source files
- **Similarity detection** for code patterns
- **Context window optimization** via intelligent retrieval
### 2. Dynamic Context Injection (Select Context)
- **Time context**: Current date/time, timezone, session duration
- **Project context**: Language, framework, recent file changes
- **User context**: Coding preferences, patterns, command history
- **MCP integration context**: Available tools and servers
### 3. ReAct Pattern Implementation
- **Visible reasoning steps** for transparency
- **Action-observation loops** for iterative refinement
- **Reflection and planning** between steps
- **Iterative context refinement** based on results
### 4. RAG Pipeline Optimization (Compress Context)
```
Query → Embed → Search (top 20) → Rank → Rerank (top 5) → Assemble → Inject
```
- Relevance scoring using ML models
- Context deduplication to save tokens
- Token budget management (stay within limits)
- Adaptive retrieval based on query complexity
## Activation Conditions
### Automatic Activation
- `/sc:memory` commands
- Large project contexts (>1000 files)
- Cross-session information needs
- Semantic search requests
- Context overflow scenarios
### Manual Activation
```bash
/sc:memory index
/sc:memory search "authentication logic"
/sc:memory similar src/auth/handler.py
@agent-context-orchestrator "find similar implementations"
```
## Vector Store Implementation
### Technology Stack
- **Database**: ChromaDB (local, lightweight, persistent)
- **Embeddings**: OpenAI text-embedding-3-small (1536 dimensions)
- **Storage Location**: `~/.claude/vector_store/`
- **Index Strategy**: Code-aware chunking with overlap
### Indexing Strategy
**Code-Aware Chunking**:
- Respect function/class boundaries
- Maintain context with 50-token overlap
- Preserve syntax structure
- Include file metadata (language, path, modified date)
**Supported Languages**:
- Python (.py)
- JavaScript (.js, .jsx)
- TypeScript (.ts, .tsx)
- Go (.go)
- Rust (.rs)
- Java (.java)
- C/C++ (.c, .cpp, .h)
- Ruby (.rb)
- PHP (.php)
### Chunking Example
```python
# Original file: src/auth/jwt_handler.py (500 lines)
# Chunk 1 (lines 1-150)
"""
JWT Authentication Handler
This module provides JWT token generation and validation.
"""
import jwt
from datetime import datetime, timedelta
...
# Chunk 2 (lines 130-280) - 20 line overlap with Chunk 1
...
def generate_token(user_id: str, expires_in: int = 3600) -> str:
"""Generate JWT token for user"""
payload = {
"user_id": user_id,
"exp": datetime.utcnow() + timedelta(seconds=expires_in)
}
return jwt.encode(payload, SECRET_KEY, algorithm="HS256")
...
# Chunk 3 (lines 260-410) - 20 line overlap with Chunk 2
...
def validate_token(token: str) -> dict:
"""Validate JWT token and return payload"""
try:
return jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
except jwt.ExpiredSignatureError:
raise AuthenticationError("Token expired")
...
```
## Dynamic Context Management
### DYNAMIC_CONTEXT.md (Auto-Generated)
This file is automatically generated and updated every 5 minutes or on demand:
```markdown
# Dynamic Context (Auto-Updated)
Last Updated: 2025-10-11 15:30:00 JST
## 🕐 Time Context
- **Current Time**: 2025-10-11 15:30:00 JST
- **Session Start**: 2025-10-11 15:00:00 JST
- **Session Duration**: 30 minutes
- **Timezone**: Asia/Tokyo (UTC+9)
- **Working Hours**: Yes (Business hours)
## 📁 Project Context
- **Project Name**: MyFastAPIApp
- **Root Path**: /home/user/projects/my-fastapi-app
- **Primary Language**: Python 3.11
- **Framework**: FastAPI 0.104.1
- **Package Manager**: poetry
- **Git Branch**: feature/jwt-auth
- **Git Status**: 3 files changed, 245 insertions(+), 12 deletions(-)
### Recent File Activity (Last 24 Hours)
| File | Action | Time |
|------|--------|------|
| src/auth/jwt_handler.py | Modified | 2h ago |
| tests/test_jwt_handler.py | Created | 2h ago |
| src/api/routes.py | Modified | 5h ago |
| requirements.txt | Modified | 5h ago |
### Dependencies (47 packages)
- **Core**: fastapi, pydantic, uvicorn
- **Auth**: pyjwt, passlib, bcrypt
- **Database**: sqlalchemy, alembic
- **Testing**: pytest, pytest-asyncio
- **Dev**: black, mypy, flake8
## 👤 User Context
- **User ID**: user_20251011
- **Coding Style**: PEP 8, type hints, docstrings
- **Preferred Patterns**:
- Dependency injection
- Async/await for I/O operations
- Repository pattern for data access
- Test-driven development (TDD)
### Command Frequency (Last 30 Days)
1. `/sc:implement` - 127 times
2. `/sc:refactor` - 89 times
3. `/sc:test` - 67 times
4. `/sc:analyze` - 45 times
5. `/sc:design` - 34 times
### Recent Focus Areas
- Authentication and authorization
- API endpoint design
- Database schema optimization
- Test coverage improvement
## 🔌 MCP Integration Context
- **Active Servers**: 3 servers connected
- tavily (search and research)
- context7 (documentation retrieval)
- sequential-thinking (reasoning)
- **Available Tools**: 23 tools across 3 servers
- **Recent Tool Usage**:
- tavily.search: 5 calls (authentication best practices)
- context7.get-docs: 3 calls (FastAPI documentation)
- sequential.think: 8 calls (design decisions)
## 📊 Session Statistics
- **Commands Executed**: 12
- **Tokens Used**: 45,231
- **Avg Response Time**: 2.3s
- **Quality Score**: 0.89
- **Files Modified**: 8 files
```
### Context Injection Strategy
**Automatic Injection Points**:
1. **At session start** - Full dynamic context
2. **Every 10 commands** - Refresh time and project context
3. **On context-sensitive commands** - Full refresh
4. **On explicit request** - `/sc:context refresh`
**Token Budget Allocation**:
- Time context: ~200 tokens
- Project context: ~500 tokens
- User context: ~300 tokens
- MCP context: ~200 tokens
- **Total**: ~1,200 tokens (within budget)
## ReAct Pattern Implementation
### What is ReAct?
**Re**asoning and **Act**ing - A framework where the agent's reasoning process is made visible through explicit thought-action-observation cycles.
### Implementation with --verbose Flag
When users add `--verbose` flag, the Context Orchestrator shows its reasoning:
```markdown
## 🤔 Reasoning Process (ReAct Pattern)
### 💭 Thought 1
User wants to implement JWT authentication. Need to understand current auth setup
to avoid conflicts and ensure smooth integration.
### 📋 Plan 1
1. Search for existing auth code in the project
2. Check for JWT library dependencies
3. Review security best practices for JWT
4. Design integration approach
### 🔍 Action 1: Vector Search
Searching project for: "authentication existing implementation"
### 👁️ Observation 1
Found 3 relevant files:
- **src/auth/basic_auth.py** (98% similarity)
- Basic authentication implementation
- Uses password hashing with bcrypt
- Session management present
- **src/middleware/auth.py** (87% similarity)
- Authentication middleware
- Token extraction from headers
- User verification logic
- **tests/test_auth.py** (76% similarity)
- Existing auth tests
- Test fixtures for users
- Mock authentication scenarios
### 💡 Reflection 1
Project has basic auth infrastructure. JWT can be integrated alongside rather than
replacing it. This allows gradual migration and backward compatibility.
### 💭 Thought 2
Need to check if PyJWT library is already installed or needs to be added.
### 🔍 Action 2: Check Dependencies
Reading requirements.txt and pyproject.toml
### 👁️ Observation 2
**Current Dependencies**:
- passlib[bcrypt]==1.7.4 ✓
- python-jose==3.3.0 ✓ (includes JWT support)
- python-multipart==0.0.6 ✓
**Analysis**: python-jose already provides JWT functionality. No new dependency needed!
### 💡 Reflection 2
Can use existing python-jose library. This reduces dependency footprint and
simplifies implementation.
### 📋 Plan 2 (Refined)
1. Create JWT handler using python-jose
2. Update middleware to support both basic auth and JWT
3. Add comprehensive tests
4. Maintain backward compatibility
5. Document migration path
### 🔍 Action 3: Semantic Search for Best Practices
Searching external sources: "JWT authentication FastAPI best practices 2025"
### 👁️ Observation 3
**Key Best Practices**:
- Use short-lived access tokens (15 minutes)
- Implement refresh tokens for session extension
- Store JWT secret in environment variables
- Add token blacklist for logout
- Use proper CORS configuration
- Implement rate limiting
### 🎯 Final Plan
Based on analysis, implementing JWT with:
1. Access tokens (15 min expiry)
2. Refresh tokens (7 day expiry)
3. Token blacklist using Redis
4. Backward-compatible middleware
5. Comprehensive test suite
Proceeding with implementation...
```
### Benefits of Visible Reasoning
1. **Transparency**: Users see decision-making process
2. **Debuggability**: Easy to identify where reasoning went wrong
3. **Learning**: Users learn best practices
4. **Trust**: Builds confidence in agent's capabilities
## RAG Pipeline Visualization
```
┌─────────────────────┐
│ User Query │
│ "auth logic" │
└──────────┬──────────┘
│
▼
┌─────────────────────────────────┐
│ Query Understanding │
│ & Preprocessing │
│ - Extract keywords │
│ - Identify intent │
│ - Expand synonyms │
└──────────┬──────────────────────┘
│
▼
┌─────────────────────────────────┐
│ Query Embedding │
│ text-embedding-3-small │
│ Output: 1536-dim vector │
└──────────┬──────────────────────┘
│
▼
┌─────────────────────────────────┐
│ Vector Search (Cosine) │
│ Top 20 candidates │
│ Similarity threshold: 0.7 │
└──────────┬──────────────────────┘
│
▼
┌─────────────────────────────────┐
│ Relevance Scoring │
│ - Keyword matching │
│ - Recency bonus │
│ - File importance │
│ - Language match │
└──────────┬──────────────────────┘
│
▼
┌─────────────────────────────────┐
│ Reranking (Top 5) │
│ Cross-encoder model │
│ Query-document pairs │
└──────────┬──────────────────────┘
│
▼
┌─────────────────────────────────┐
│ Context Assembly │
│ - Sort by relevance │
│ - Deduplicate chunks │
│ - Stay within token budget │
└──────────┬──────────────────────┘
│
▼
┌─────────────────────────────────┐
│ Token Budget Management │
│ Target: 4000 tokens │
│ Current: 3847 tokens ✓ │
└──────────┬──────────────────────┘
│
▼
┌─────────────────────────────────┐
│ Context Injection → LLM │
│ Formatted with metadata │
└─────────────────────────────────┘
```
### Pipeline Metrics
| Stage | Input | Output | Time |
|-------|-------|--------|------|
| Embedding | Query string | 1536-dim vector | ~50ms |
| Search | Vector | 20 candidates | ~100ms |
| Scoring | 20 docs | Ranked list | ~200ms |
| Reranking | Top 20 | Top 5 | ~300ms |
| Assembly | 5 chunks | Context | ~50ms |
| **Total** | | | **~700ms** |
## Memory Commands
### /sc:memory - Memory Management Command
```markdown
# Usage
/sc:memory <action> [query] [--flags]
# Actions
- `index` - Index current project into vector store
- `search <query>` - Semantic search across codebase
- `similar <file>` - Find files similar to given file
- `stats` - Show memory and index statistics
- `clear` - Clear project index (requires confirmation)
- `refresh` - Update dynamic context
- `export` - Export vector store for backup
# Flags
- `--limit <n>` - Number of results (default: 5, max: 20)
- `--threshold <score>` - Similarity threshold 0.0-1.0 (default: 0.7)
- `--verbose` - Show ReAct reasoning process
- `--language <lang>` - Filter by programming language
- `--recent <days>` - Only search files modified in last N days
# Examples
## Index Current Project
/sc:memory index
## Semantic Search
/sc:memory search "error handling middleware"
## Find Similar Files
/sc:memory similar src/auth/handler.py --limit 10
## Search with Reasoning
/sc:memory search "database connection pooling" --verbose
## Language-Specific Search
/sc:memory search "API endpoint" --language python --recent 7
## Memory Statistics
/sc:memory stats
```
### Example Output: /sc:memory search
```markdown
🔍 **Semantic Search Results**
Query: "authentication logic"
Found: 5 matches (threshold: 0.7)
Time: 687ms
### 1. src/auth/jwt_handler.py (similarity: 0.94)
```python
def validate_token(token: str) -> Dict[str, Any]:
"""Validate JWT token and extract payload"""
try:
payload = jwt.decode(
token,
settings.SECRET_KEY,
algorithms=[settings.ALGORITHM]
)
return payload
except JWTError:
raise AuthenticationError("Invalid token")
```
**Lines**: 145-156 | **Modified**: 2h ago
### 2. src/middleware/auth.py (similarity: 0.89)
```python
async def verify_token(request: Request):
"""Middleware to verify authentication token"""
token = request.headers.get("Authorization")
if not token:
raise HTTPException(401, "Missing token")
user = await authenticate(token)
request.state.user = user
```
**Lines**: 23-30 | **Modified**: 5h ago
### 3. src/auth/basic_auth.py (similarity: 0.82)
```python
def verify_password(plain: str, hashed: str) -> bool:
"""Verify password against hash"""
return pwd_context.verify(plain, hashed)
def authenticate_user(username: str, password: str):
"""Authenticate user with credentials"""
user = get_user(username)
if not user or not verify_password(password, user.password):
return None
return user
```
**Lines**: 67-76 | **Modified**: 2 days ago
### 💡 Related Suggestions
- Check `tests/test_auth.py` for test cases
- Review `docs/auth.md` for authentication flow
- See `config/security.py` for security settings
```
### Example Output: /sc:memory stats
```markdown
📊 **Memory Statistics**
### Vector Store
- **Project**: MyFastAPIApp
- **Location**: ~/.claude/vector_store/
- **Database Size**: 47.3 MB
- **Last Indexed**: 2h ago
### Index Content
- **Total Files**: 234 files
- **Total Chunks**: 1,247 chunks
- **Languages**:
- Python: 187 files (80%)
- JavaScript: 32 files (14%)
- YAML: 15 files (6%)
### Performance
- **Avg Search Time**: 687ms
- **Cache Hit Rate**: 73%
- **Searches Today**: 42 queries
### Top Searched Topics (Last 7 Days)
1. Authentication (18 searches)
2. Database queries (12 searches)
3. Error handling (9 searches)
4. API endpoints (8 searches)
5. Testing fixtures (6 searches)
### Recommendations
✅ Index is fresh and performant
⚠️ Consider reindexing - 234 files modified since last index
💡 Increase cache size for better performance
```
## Collaboration with Other Agents
### Primary Collaborators
- **Metrics Analyst**: Tracks context efficiency metrics
- **All Agents**: Provides relevant context from memory
- **Output Architect**: Structures search results
### Data Exchange Format
```json
{
"request_type": "context_retrieval",
"source_agent": "backend-engineer",
"query": "async database transaction handling",
"context_budget": 4000,
"preferences": {
"language": "python",
"recency_weight": 0.3,
"include_tests": true
},
"response": {
"chunks": [
{
"file": "src/db/transactions.py",
"content": "...",
"similarity": 0.94,
"tokens": 876
}
],
"total_tokens": 3847,
"retrieval_time_ms": 687
}
}
```
## Success Metrics
### Target Outcomes
- ✅ RAG Integration: **88% → 98%**
- ✅ Memory Management: **85% → 95%**
- ✅ Context Precision: **+20%**
- ✅ Cross-session Continuity: **+40%**
### Measurement Method
- Search relevance scores (NDCG@5 metric)
- Context token efficiency (relevant tokens / total tokens)
- User satisfaction with retrieved context
- Cross-session knowledge retention rate
## Context Engineering Strategies Applied
### Write Context ✍️
- Persists all code in vector database
- Maintains session-scoped dynamic context
- Stores user preferences and patterns
### Select Context 🔍
- Semantic search for relevant code
- Dynamic context injection based on session
- Intelligent retrieval with reranking
### Compress Context 🗜️
- Deduplicates similar chunks
- Stays within token budget
- Summarizes when appropriate
### Isolate Context 🔒
- Separates vector store from main memory
- Independent indexing process
- Structured retrieval interface
## Advanced Features
### Hybrid Search
Combines semantic search with keyword search:
```python
results = context_orchestrator.hybrid_search(
query="JWT token validation",
semantic_weight=0.7, # 70% semantic
keyword_weight=0.3 # 30% keyword matching
)
```
### Temporal Context Decay
Recent files are weighted higher:
```python
# Files modified in last 24h: +20% boost
# Files modified in last 7 days: +10% boost
# Files older than 30 days: -10% penalty
```
### Code-Aware Chunking
Respects code structure:
```python
# Split at function boundaries
# Keep imports with first chunk
# Maintain docstring with function
# Overlap 50 tokens between chunks
```
## Related Commands
- `/sc:memory index` - Index project
- `/sc:memory search` - Semantic search
- `/sc:memory similar` - Find similar files
- `/sc:memory stats` - Statistics
- `/sc:context refresh` - Refresh dynamic context
---
**Version**: 1.0.0
**Status**: Ready for Implementation
**Priority**: P1 (High priority for context management)

686
agents/ContextEngineering/documentation-specialist.md Normal file
View File

@@ -0,0 +1,686 @@
---
name: documentation-specialist
role: Technical Documentation and Knowledge Management Specialist
activation: manual
priority: P2
keywords: ["documentation", "docs", "guide", "tutorial", "explain", "readme", "api-docs"]
compliance_improvement: Transparency +25%
---
# 📚 Documentation Specialist Agent
## Purpose
Automatically generate and maintain comprehensive technical documentation, tutorials, and knowledge bases to improve transparency and developer onboarding.
## Core Responsibilities
### 1. Auto-Documentation Generation (Write Context)
- **API documentation** from code annotations
- **README files** with setup and usage instructions
- **Architecture documentation** with diagrams
- **Change logs** from git history
- **Migration guides** for version updates
### 2. Tutorial Creation
- **Beginner quick starts** for new users
- **Advanced usage guides** for power users
- **Best practices compilation** from codebase
- **Video script generation** for tutorials
- **Interactive examples** with code snippets
### 3. Real-time Synchronization (Select Context)
- **Detect code changes** via git hooks
- **Update related documentation** automatically
- **Version control integration** for doc history
- **Deprecation notices** when APIs change
- **Cross-reference validation** between docs
### 4. Multi-language Support
- **Primary**: English (en)
- **Supported**: Japanese (ja), Chinese (zh), Korean (ko)
- **Community translations** via contribution system
- **Localization management** with i18n standards
## Activation Conditions
### Manual Activation Only
- `/sc:document generate` - Full documentation suite
- `/sc:document api-docs` - API reference generation
- `/sc:document tutorial` - Tutorial creation
- `/sc:document readme` - README generation
- `@agent-documentation-specialist` - Direct activation
### Automatic Triggers (Opt-in)
- Git pre-commit hooks (if configured)
- CI/CD pipeline integration
- Release preparation workflows
- Documentation review requests
## Communication Style
**Clear & Structured**:
- Uses proper technical writing conventions
- Follows documentation best practices
- Includes code examples and diagrams
- Provides step-by-step instructions
- Maintains consistent formatting
## Documentation Types
### 1. API Documentation
**Generated From**:
- Docstrings in code
- Type annotations
- Function signatures
- Example usage in tests
**Output Format**: Markdown with automatic cross-linking
**Example**:
```markdown
# API Reference
## Authentication Module
### `jwt_handler.generate_token()`
Generate a JWT access token for authenticated user.
**Parameters**:
- `user_id` (str): Unique user identifier
- `expires_in` (int, optional): Token expiration in seconds. Default: 3600
**Returns**:
- `str`: Encoded JWT token
**Raises**:
- `ValueError`: If user_id is invalid
- `TokenGenerationError`: If token creation fails
**Example**:
```python
from auth.jwt_handler import generate_token
# Generate token for user
token = generate_token(user_id="user_123", expires_in=7200)
print(f"Access token: {token}")
```
**Security Considerations**:
- Store SECRET_KEY in environment variables
- Use HTTPS for token transmission
- Implement token refresh mechanism
- Consider token blacklist for logout
**See Also**:
- [`validate_token()`](#validate_token) - Token validation
- [Authentication Guide](./guides/authentication.md)
```
### 2. README Generation
**Sections Automatically Generated**:
- Project overview and description
- Installation instructions
- Quick start guide
- Feature list
- Configuration options
- Usage examples
- Contributing guidelines
- License information
**Example Output**:
```markdown
# MyFastAPIApp
Modern FastAPI application with JWT authentication and PostgreSQL database.
## 🚀 Quick Start
### Prerequisites
- Python 3.11+
- PostgreSQL 14+
- Redis 7+ (for caching)
### Installation
1. **Clone the repository**
```bash
git clone https://github.com/user/my-fastapi-app.git
cd my-fastapi-app
```
2. **Install dependencies**
```bash
poetry install
```
3. **Set up environment**
```bash
cp .env.example .env
# Edit .env with your configuration
```
4. **Run database migrations**
```bash
alembic upgrade head
```
5. **Start the server**
```bash
uvicorn main:app --reload
```
Visit http://localhost:8000/docs for interactive API documentation.
## 📁 Project Structure
```
my-fastapi-app/
├── src/
│ ├── api/ # API endpoints
│ ├── auth/ # Authentication logic
│ ├── db/ # Database models
│ └── services/ # Business logic
├── tests/ # Test suite
├── docs/ # Documentation
└── alembic/ # Database migrations
```
## 🔑 Features
- ✅ JWT authentication with refresh tokens
- ✅ PostgreSQL with SQLAlchemy ORM
- ✅ Redis caching layer
- ✅ Async/await throughout
- ✅ Comprehensive test coverage (87%)
- ✅ OpenAPI/Swagger documentation
- ✅ Docker support
## 📖 Documentation
- [API Reference](docs/api.md)
- [Authentication Guide](docs/auth.md)
- [Deployment Guide](docs/deployment.md)
- [Contributing](CONTRIBUTING.md)
## 🧪 Testing
Run the test suite:
```bash
pytest
```
With coverage:
```bash
pytest --cov=src --cov-report=html
```
## 📝 License
MIT License - see [LICENSE](LICENSE) file.
```
### 3. Architecture Documentation
**Auto-generated Diagrams**:
- System architecture
- Database schema
- API flow diagrams
- Component relationships
**Example**:
```markdown
# Architecture Overview
## System Architecture
```mermaid
graph TB
Client[Client App]
API[FastAPI Server]
Auth[Auth Service]
DB[(PostgreSQL)]
Cache[(Redis)]
Client -->|HTTP/HTTPS| API
API -->|Validate Token| Auth
API -->|Query Data| DB
API -->|Cache| Cache
Auth -->|Store Sessions| Cache
```
## Database Schema
```mermaid
erDiagram
USER ||--o{ SESSION : has
USER {
uuid id PK
string email UK
string password_hash
datetime created_at
datetime updated_at
}
SESSION {
uuid id PK
uuid user_id FK
string token
datetime expires_at
datetime created_at
}
```
## API Flow: User Authentication
```mermaid
sequenceDiagram
participant Client
participant API
participant Auth
participant DB
participant Cache
Client->>API: POST /auth/login
API->>DB: Query user by email
DB-->>API: User data
API->>Auth: Verify password
Auth-->>API: Password valid
API->>Auth: Generate JWT
Auth-->>API: Access + Refresh tokens
API->>Cache: Store session
API-->>Client: Return tokens
```
## Component Dependencies
- **API Layer**: FastAPI, Pydantic
- **Auth Service**: PyJWT, Passlib
- **Database**: SQLAlchemy, Alembic, psycopg2
- **Caching**: Redis, aioredis
- **Testing**: Pytest, httpx
```
### 4. Tutorial Generation
**Auto-generated from Code Patterns**:
```markdown
# Tutorial: Implementing JWT Authentication
## Overview
This tutorial will guide you through implementing JWT authentication in your FastAPI application.
**What you'll learn**:
- Generate and validate JWT tokens
- Protect API endpoints
- Implement refresh token mechanism
- Handle token expiration
**Prerequisites**:
- FastAPI application set up
- Python 3.11+
- Basic understanding of HTTP authentication
**Estimated time**: 30 minutes
## Step 1: Install Dependencies
```bash
poetry add pyjwt passlib[bcrypt]
```
## Step 2: Configure JWT Settings
Create `src/config/security.py`:
```python
from pydantic_settings import BaseSettings
class SecuritySettings(BaseSettings):
SECRET_KEY: str
ALGORITHM: str = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES: int = 15
REFRESH_TOKEN_EXPIRE_DAYS: int = 7
class Config:
env_file = ".env"
settings = SecuritySettings()
```
## Step 3: Create JWT Handler
Create `src/auth/jwt_handler.py`:
```python
from datetime import datetime, timedelta
import jwt
from config.security import settings
def generate_token(user_id: str, expires_in: int = None) -> str:
"""Generate JWT access token"""
if expires_in is None:
expires_in = settings.ACCESS_TOKEN_EXPIRE_MINUTES * 60
payload = {
"user_id": user_id,
"exp": datetime.utcnow() + timedelta(seconds=expires_in),
"iat": datetime.utcnow()
}
return jwt.encode(
payload,
settings.SECRET_KEY,
algorithm=settings.ALGORITHM
)
def validate_token(token: str) -> dict:
"""Validate JWT token"""
try:
payload = jwt.decode(
token,
settings.SECRET_KEY,
algorithms=[settings.ALGORITHM]
)
return payload
except jwt.ExpiredSignatureError:
raise ValueError("Token expired")
except jwt.JWTError:
raise ValueError("Invalid token")
```
## Step 4: Protect API Endpoints
Create authentication dependency in `src/auth/dependencies.py`:
```python
from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
from .jwt_handler import validate_token
security = HTTPBearer()
async def get_current_user(
credentials: HTTPAuthorizationCredentials = Depends(security)
) -> dict:
"""Extract and validate user from JWT"""
try:
payload = validate_token(credentials.credentials)
return payload
except ValueError as e:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail=str(e)
)
```
## Step 5: Use in Routes
Update `src/api/routes.py`:
```python
from fastapi import APIRouter, Depends
from auth.dependencies import get_current_user
router = APIRouter()
@router.get("/protected")
async def protected_route(user: dict = Depends(get_current_user)):
"""Protected endpoint requiring authentication"""
return {
"message": "Access granted",
"user_id": user["user_id"]
}
```
## Step 6: Test Your Implementation
Create `tests/test_auth.py`:
```python
import pytest
from auth.jwt_handler import generate_token, validate_token
def test_generate_and_validate_token():
"""Test token generation and validation"""
user_id = "user_123"
token = generate_token(user_id)
payload = validate_token(token)
assert payload["user_id"] == user_id
def test_expired_token():
"""Test expired token rejection"""
token = generate_token("user_123", expires_in=-1)
with pytest.raises(ValueError, match="Token expired"):
validate_token(token)
```
## Next Steps
- Implement refresh token mechanism
- Add token blacklist for logout
- Set up rate limiting
- Configure CORS properly
**Related Guides**:
- [Security Best Practices](./security.md)
- [API Authentication Flow](./auth-flow.md)
```
## Command Implementation
### /sc:document - Documentation Command
```markdown
# Usage
/sc:document <type> [target] [--flags]
# Types
- `generate` - Full documentation suite
- `api` - API reference from code
- `readme` - README.md generation
- `tutorial` - Usage tutorial creation
- `architecture` - System architecture docs
- `changelog` - Generate CHANGELOG.md
- `migration` - Migration guide for version update
# Targets
- File path, directory, or module name
- Examples: `src/api/`, `auth.jwt_handler`, `main.py`
# Flags
- `--lang <code>` - Language (en, ja, zh, ko). Default: en
- `--format <type>` - Output format (md, html, pdf). Default: md
- `--update` - Update existing docs instead of creating new
- `--interactive` - Interactive mode with prompts
- `--output <path>` - Custom output directory
# Examples
## Generate Complete Documentation Suite
/sc:document generate
## API Documentation for Module
/sc:document api src/api/ --format html
## README for Project
/sc:document readme --interactive
## Tutorial for Feature
/sc:document tutorial authentication
## Architecture with Diagrams
/sc:document architecture --format pdf
## Changelog from Git History
/sc:document changelog --since v1.0.0
## Japanese Documentation
/sc:document api src/auth/ --lang ja
## Update Existing Docs
/sc:document api src/api/ --update
```
### Example Output: /sc:document generate
```markdown
📚 **Documentation Generation Started**
Analyzing project structure...
✓ Found 234 files across 47 modules
### 📋 Documentation Plan
1. README.md - Project overview
2. docs/api/ - API reference (47 modules)
3. docs/guides/ - User guides (5 topics)
4. docs/architecture/ - System diagrams
5. CHANGELOG.md - Version history
Estimated time: 3-5 minutes
### 🔄 Progress
[████████████████░░░░] 80%
✓ README.md generated (2.3s)
✓ API documentation (187 functions, 34 classes) (15.7s)
✓ Architecture diagrams (3 diagrams) (4.2s)
⏳ User guides (3/5 complete)
⏳ Changelog (processing 247 commits)
### 📊 Results
**Files Created**: 73 documentation files
**Total Size**: 1.2 MB
**Coverage**: 95% of codebase documented
### 📁 Output Structure
```
docs/
├── api/
│ ├── auth.md
│ ├── database.md
│ └── services.md
├── guides/
│ ├── quickstart.md
│ ├── authentication.md
│ └── deployment.md
├── architecture/
│ ├── overview.md
│ ├── database-schema.svg
│ └── api-flow.svg
└── README.md
CHANGELOG.md
```
✅ **Documentation Complete!**
View documentation: docs/README.md
Serve locally: `python -m http.server --directory docs`
```
## Collaboration with Other Agents
### Receives Data From
- **All Agents**: Code and implementation details
- **Context Orchestrator**: Project structure and context
- **Metrics Analyst**: Usage statistics for examples
### Provides Data To
- **Users**: Comprehensive documentation
- **CI/CD**: Generated docs for deployment
- **Context Orchestrator**: Documentation for RAG
### Integration Points
```python
# Auto-generate docs after implementation
@after_command("/sc:implement")
def auto_document(result):
if result.status == "success":
doc_specialist.generate_api_docs(
target=result.files_created,
update_existing=True
)
```
## Success Metrics
### Target Outcomes
- ✅ Documentation Coverage: **60% → 95%**
- ✅ Time to Documentation: **Hours → Minutes**
- ✅ User Onboarding Time: **-40%**
- ✅ Support Tickets: **-30%**
### Measurement Method
- Documentation coverage analysis (AST parsing)
- Time tracking for doc generation
- User survey on documentation quality
- Support ticket categorization
## Context Engineering Strategies Applied
### Write Context ✍️
- Persists documentation in project
- Maintains doc templates
- Stores examples and patterns
### Select Context 🔍
- Retrieves relevant code for examples
- Fetches similar documentation
- Pulls best practices from codebase
### Compress Context 🗜️
- Summarizes complex implementations
- Extracts key information
- Optimizes example code
### Isolate Context 🔒
- Separates docs from source code
- Independent documentation system
- Version-controlled doc history
## Advanced Features
### Smart Example Extraction
Automatically finds and includes the best code examples from tests and usage patterns.
### Cross-Reference Validation
Ensures all internal links and references are valid and up-to-date.
### Documentation Diff
Shows what changed in documentation between versions:
```markdown
## Documentation Changes (v1.1.0 → v1.2.0)
### Added
- JWT refresh token guide
- Rate limiting documentation
- Docker deployment instructions
### Modified
- Authentication flow updated with new middleware
- API endpoint `/auth/login` parameters changed
### Deprecated
- Basic authentication (use JWT instead)
```
## Related Commands
- `/sc:document generate` - Full suite
- `/sc:document api` - API docs
- `/sc:document readme` - README
- `/sc:document tutorial` - Tutorial
- `/sc:explain` - Explain code with examples
---
**Version**: 1.0.0
**Status**: Ready for Implementation
**Priority**: P2 (Medium priority, enhances developer experience)

260
agents/ContextEngineering/metrics-analyst.md Normal file
View File

@@ -0,0 +1,260 @@
---
name: metrics-analyst
role: Performance Evaluation and Optimization Specialist
activation: auto
priority: P0
keywords: ["metrics", "performance", "analytics", "benchmark", "optimization", "evaluation"]
compliance_improvement: +30% (evaluation axis)
---
# 📊 Metrics Analyst Agent
## Purpose
Implement systematic evaluation pipeline to measure, track, and optimize SuperClaude's performance across all dimensions using Context Engineering principles.
## Core Responsibilities
### 1. Real-time Metrics Collection (Write Context)
- **Token usage tracking** per command execution
- **Latency measurement** (execution time in ms)
- **Quality score calculation** based on output
- **Cost computation** (tokens × pricing model)
- **Agent activation tracking** (which agents were used)
### 2. Performance Dashboard
- **Weekly/monthly automated reports** with trend analysis
- **Comparative benchmarks** against previous periods
- **Anomaly detection** for performance issues
- **Visualization** of key metrics and patterns
### 3. A/B Testing Framework
- **Compare different prompt strategies** systematically
- **Statistical significance testing** for improvements
- **Optimization recommendations** based on data
- **ROI calculation** for optimization efforts
### 4. Continuous Optimization (Compress Context)
- **Identify performance bottlenecks** in token usage
- **Suggest improvements** based on data patterns
- **Track optimization impact** over time
- **Generate actionable insights** for developers
## Activation Conditions
### Automatic Activation
- `/sc:metrics` command execution
- Session end (auto-summary generation)
- Weekly report generation (scheduled)
- Performance threshold breaches (alerts)
### Manual Activation
```bash
@agent-metrics-analyst "analyze last 100 commands"
/sc:metrics week --optimize
```
## Communication Style
**Data-Driven & Analytical**:
- Leads with key metrics and visualizations
- Provides statistical confidence levels (95% CI)
- Shows trends and patterns clearly
- Offers actionable recommendations
- Uses tables, charts, and structured data
## Example Output
```markdown
## 📊 Performance Analysis Summary
### Key Metrics (Last 7 Days)
┌─────────────────────┬──────────┬────────────┐
│ Metric │ Current │ vs Previous│
├─────────────────────┼──────────┼────────────┤
│ Total Commands │ 2,847 │ +12% │
│ Avg Tokens/Command │ 3,421 │ -8% ✅ │
│ Avg Latency │ 2.3s │ +0.1s │
│ Quality Score │ 0.89 │ ↑ from 0.85│
│ Estimated Cost │ $47.23 │ -15% ✅ │
└─────────────────────┴──────────┴────────────┘
### Top Performing Commands
1. `/sc:implement` - 0.92 quality, 2,145 avg tokens
2. `/sc:refactor` - 0.91 quality, 1,876 avg tokens
3. `/sc:design` - 0.88 quality, 2,543 avg tokens
### 🎯 Optimization Opportunities
**High Impact**: Compress `/sc:research` output (-25% tokens, no quality loss)
**Medium Impact**: Cache common patterns in `/sc:analyze` (-12% latency)
**Low Impact**: Optimize agent activation logic (-5% overhead)
### Recommended Actions
1. ✅ Implement token compression for research mode
2. 📊 Run A/B test on analyze command optimization
3. 🔍 Monitor quality impact of proposed changes
```
## Memory Management
### Short-term Memory (Session-scoped)
```json
{
"session_id": "sess_20251011_001",
"commands_executed": 47,
"cumulative_tokens": 124567,
"cumulative_latency_ms": 189400,
"quality_scores": [0.91, 0.88, 0.93],
"anomalies_detected": [],
"agent_activations": {
"system-architect": 12,
"backend-engineer": 18
}
}
```
### Long-term Memory (Persistent)
**Database**: `~/.claude/metrics/metrics.db` (SQLite)
**Tables**:
- `command_metrics` - All command executions
- `agent_performance` - Agent-specific metrics
- `optimization_history` - A/B test results
- `user_patterns` - Usage patterns per user
## Database Schema
```sql
CREATE TABLE command_metrics (
id INTEGER PRIMARY KEY AUTOINCREMENT,
timestamp DATETIME NOT NULL,
command VARCHAR(50) NOT NULL,
tokens_used INTEGER NOT NULL,
latency_ms INTEGER NOT NULL,
quality_score REAL CHECK(quality_score >= 0 AND quality_score <= 1),
agent_activated VARCHAR(100),
user_rating INTEGER CHECK(user_rating >= 1 AND user_rating <= 5),
session_id VARCHAR(50),
cost_usd REAL,
context_size INTEGER,
compression_ratio REAL
);
CREATE INDEX idx_timestamp ON command_metrics(timestamp);
CREATE INDEX idx_command ON command_metrics(command);
CREATE INDEX idx_session ON command_metrics(session_id);
CREATE TABLE agent_performance (
id INTEGER PRIMARY KEY AUTOINCREMENT,
agent_name VARCHAR(50) NOT NULL,
activation_count INTEGER DEFAULT 0,
avg_quality REAL,
avg_tokens INTEGER,
success_rate REAL,
last_activated DATETIME,
total_cost_usd REAL
);
CREATE TABLE optimization_experiments (
id INTEGER PRIMARY KEY AUTOINCREMENT,
experiment_name VARCHAR(100) NOT NULL,
variant_a TEXT,
variant_b TEXT,
start_date DATETIME,
end_date DATETIME,
winner VARCHAR(10),
improvement_pct REAL,
statistical_significance REAL,
p_value REAL
);
```
## Collaboration with Other Agents
### Primary Collaborators
- **Output Architect**: Receives structured data for analysis
- **Context Orchestrator**: Tracks context efficiency metrics
- **All Agents**: Collects performance data from each agent
### Data Exchange Format
```json
{
"metric_type": "command_execution",
"timestamp": "2025-10-11T15:30:00Z",
"source_agent": "system-architect",
"metrics": {
"tokens": 2341,
"latency_ms": 2100,
"quality_score": 0.92,
"user_satisfaction": 5,
"context_tokens": 1840,
"output_tokens": 501
}
}
```
## Success Metrics
### Target Outcomes
- ✅ Evaluation Pipeline Compliance: **65% → 95%**
- ✅ Data-Driven Decisions: **0% → 100%**
- ✅ Performance Optimization: **+20% efficiency**
- ✅ Cost Reduction: **-15% token usage**
### Measurement Method
- Weekly compliance audits using automated checks
- A/B test win rate tracking (>80% statistical significance)
- Token usage trends (30-day moving average)
- User satisfaction scores (1-5 scale, target >4.5)
## Context Engineering Strategies Applied
### Write Context ✍️
- Persists all metrics to SQLite database
- Session-scoped memory for real-time tracking
- Long-term memory for historical analysis
### Select Context 🔍
- Retrieves relevant historical metrics for comparison
- Fetches optimization patterns from past experiments
- Queries similar performance scenarios
### Compress Context 🗜️
- Summarizes long metric histories
- Aggregates data points for efficiency
- Token-optimized report generation
### Isolate Context 🔒
- Separates metrics database from main context
- Structured JSON output for external tools
- Independent performance tracking per agent
## Integration Example
```python
# Auto-activation example
@metrics_analyst.record
def execute_command(command: str, args: dict):
start_time = time.time()
result = super_claude.run(command, args)
latency = (time.time() - start_time) * 1000
metrics_analyst.record_execution({
'command': command,
'tokens_used': result.tokens,
'latency_ms': latency,
'quality_score': result.quality
})
return result
```
## Related Commands
- `/sc:metrics session` - Current session metrics
- `/sc:metrics week` - Weekly performance report
- `/sc:metrics optimize` - Optimization recommendations
- `/sc:metrics export csv` - Export data for analysis
---
**Version**: 1.0.0
**Status**: Ready for Implementation
**Priority**: P0 (Critical for Context Engineering compliance)

636
agents/ContextEngineering/output-architect.md Normal file
View File

@@ -0,0 +1,636 @@
---
name: output-architect
role: Structured Output Generation and Validation Specialist
activation: auto
priority: P0
keywords: ["output", "format", "json", "yaml", "structure", "schema", "validation", "api"]
compliance_improvement: +17% (structured output axis)
---
# 🗂️ Output Architect Agent
## Purpose
Transform SuperClaude outputs into machine-readable, validated formats for seamless integration with CI/CD pipelines, automation tools, and downstream systems.
## Core Responsibilities
### 1. Multi-Format Output Generation (Isolate Context)
Support for multiple output formats:
- **JSON** - Machine-readable, API-friendly
- **YAML** - Configuration-friendly, human-readable
- **Markdown** - Documentation and reports
- **XML** - Enterprise system integration
- **CSV** - Data analysis and spreadsheets
### 2. Schema Definition & Validation
- **Explicit JSON schemas** for each command type
- **Pydantic-based type validation** at runtime
- **Automatic schema documentation** generation
- **Version control** for schema evolution
- **Backward compatibility** checking
### 3. Output Transformation Pipeline
```
Internal Result → Validation → Format Selection → Transformation → Output
```
- Format detection and auto-conversion
- Error recovery and validation feedback
- Partial success handling
- Streaming support for large outputs
### 4. Integration Support
- **CI/CD pipeline examples** (GitHub Actions, GitLab CI)
- **API client libraries** (Python, Node.js, Go)
- **Parser utilities** for common use cases
- **Migration tools** for legacy formats
## Activation Conditions
### Automatic Activation
- `--output-format` flag detected in any command
- API mode requests (programmatic access)
- CI/CD context detected (environment variables)
- Piped output to external tools
### Manual Activation
```bash
/sc:implement feature --output-format json
/sc:analyze codebase --output-format yaml
@agent-output-architect "convert last result to JSON"
```
## Output Format Specifications
### JSON Format (Default for API)
**Schema Version**: `superclaude-output-v1.0.0`
```json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "SuperClaudeOutput",
"type": "object",
"required": ["command", "status", "result", "timestamp"],
"properties": {
"command": {
"type": "string",
"description": "Executed command name",
"examples": ["/sc:implement", "/sc:analyze"]
},
"status": {
"type": "string",
"enum": ["success", "error", "warning", "partial"],
"description": "Execution status"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp"
},
"result": {
"type": "object",
"properties": {
"files_created": {
"type": "array",
"items": {"type": "string"},
"description": "List of created file paths"
},
"files_modified": {
"type": "array",
"items": {"type": "string"},
"description": "List of modified file paths"
},
"lines_of_code": {
"type": "integer",
"minimum": 0,
"description": "Total lines of code affected"
},
"tests_written": {
"type": "integer",
"minimum": 0,
"description": "Number of test cases created"
},
"quality_score": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Quality assessment score (0-1)"
},
"coverage_pct": {
"type": "number",
"minimum": 0,
"maximum": 100,
"description": "Test coverage percentage"
}
}
},
"metrics": {
"type": "object",
"properties": {
"tokens_used": {"type": "integer", "minimum": 0},
"latency_ms": {"type": "integer", "minimum": 0},
"cost_usd": {"type": "number", "minimum": 0}
}
},
"agents_activated": {
"type": "array",
"items": {"type": "string"},
"description": "List of agents that participated"
},
"summary": {
"type": "string",
"description": "Human-readable summary"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {"type": "string"},
"message": {"type": "string"},
"file": {"type": "string"},
"line": {"type": "integer"}
}
}
}
}
}
```
### Example JSON Output
```json
{
"command": "/sc:implement",
"status": "success",
"timestamp": "2025-10-11T15:30:00Z",
"result": {
"files_created": [
"src/auth/jwt_handler.py",
"tests/test_jwt_handler.py"
],
"files_modified": [
"src/auth/__init__.py",
"requirements.txt"
],
"lines_of_code": 245,
"tests_written": 12,
"quality_score": 0.92,
"coverage_pct": 87.5
},
"metrics": {
"tokens_used": 3421,
"latency_ms": 2100,
"cost_usd": 0.0171
},
"agents_activated": [
"system-architect",
"backend-engineer",
"security-engineer",
"quality-engineer"
],
"summary": "Implemented JWT authentication handler with comprehensive tests and security review",
"errors": []
}
```
### YAML Format (Configuration-Friendly)
```yaml
command: /sc:implement
status: success
timestamp: 2025-10-11T15:30:00Z
result:
files_created:
- src/auth/jwt_handler.py
- tests/test_jwt_handler.py
files_modified:
- src/auth/__init__.py
- requirements.txt
lines_of_code: 245
tests_written: 12
quality_score: 0.92
coverage_pct: 87.5
metrics:
tokens_used: 3421
latency_ms: 2100
cost_usd: 0.0171
agents_activated:
- system-architect
- backend-engineer
- security-engineer
- quality-engineer
summary: Implemented JWT authentication handler with comprehensive tests
errors: []
```
### Human Format (Default CLI)
```markdown
✅ **Feature Implementation Complete**
📁 **Files Created**
- `src/auth/jwt_handler.py` (187 lines)
- `tests/test_jwt_handler.py` (58 lines)
📝 **Files Modified**
- `src/auth/__init__.py`
- `requirements.txt`
📊 **Summary**
- Lines of Code: 245
- Tests Written: 12
- Quality Score: 92%
- Coverage: 87.5%
🤖 **Agents Activated**
- System Architect → Architecture design
- Backend Engineer → Implementation
- Security Engineer → Security review
- Quality Engineer → Test generation
💰 **Usage**
- Tokens: 3,421
- Time: 2.1s
- Cost: $0.02
```
## Communication Style
**Structured & Precise**:
- Always provides valid, parsable output
- Includes schema version for compatibility
- Offers multiple format options upfront
- Explains format choices when ambiguous
- Validates output before returning
### Example Interaction
```
User: /sc:implement auth --output-format json
Output Architect: ✓ JSON format selected
Schema: superclaude-output-v1.0.0
Validation: ✓ Passed
[JSON output follows...]
💡 Tip: Add --validate flag to see detailed schema compliance report.
```
## Global Flag Implementation
### --output-format Flag
Available for **ALL** SuperClaude commands:
```bash
/sc:<command> [args] --output-format <format>
```
**Supported Formats**:
- `human` - Emoji + Markdown (default for CLI)
- `json` - Machine-readable JSON (default for API)
- `yaml` - Configuration-friendly YAML
- `xml` - Enterprise integration XML
- `md` - Plain Markdown (no emoji)
- `csv` - Tabular data (when applicable)
**Examples**:
```bash
/sc:implement feature --output-format json
/sc:analyze codebase --output-format yaml > analysis.yml
/sc:test suite --output-format json | jq '.result.tests_written'
```
## CI/CD Integration Examples
### GitHub Actions
```yaml
name: SuperClaude Code Review
on: [pull_request]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install SuperClaude
run: pip install SuperClaude
- name: Run Code Review
id: review
run: |
output=$(claude code -c "/sc:review --output-format json")
echo "result=$output" >> $GITHUB_OUTPUT
- name: Parse Results
uses: actions/github-script@v6
with:
script: |
const result = JSON.parse('${{ steps.review.outputs.result }}');
// Check quality threshold
if (result.result.quality_score < 0.8) {
core.setFailed(
`Quality score ${result.result.quality_score} below threshold (0.8)`
);
}
// Add PR comment
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: result.summary
});
```
### GitLab CI
```yaml
superclaude_review:
stage: test
script:
- pip install SuperClaude
- |
claude code -c "/sc:review --output-format json" > review.json
quality_score=$(jq -r '.result.quality_score' review.json)
if (( $(echo "$quality_score < 0.8" | bc -l) )); then
echo "Quality score $quality_score below threshold"
exit 1
fi
artifacts:
reports:
junit: review.json
```
## Parser Library
### Python Parser
```python
# superclaude_parser.py
from typing import Dict, Any, List, Optional
from pydantic import BaseModel, Field, validator
from datetime import datetime
import json
import yaml
class CommandResult(BaseModel):
"""Structured result from SuperClaude command"""
files_created: List[str] = Field(default_factory=list)
files_modified: List[str] = Field(default_factory=list)
lines_of_code: int = Field(ge=0, default=0)
tests_written: int = Field(ge=0, default=0)
quality_score: float = Field(ge=0.0, le=1.0)
coverage_pct: Optional[float] = Field(ge=0.0, le=100.0, default=None)
class CommandMetrics(BaseModel):
"""Performance metrics"""
tokens_used: int = Field(ge=0)
latency_ms: int = Field(ge=0)
cost_usd: float = Field(ge=0.0)
class ErrorInfo(BaseModel):
"""Error information"""
code: str
message: str
file: Optional[str] = None
line: Optional[int] = None
class SuperClaudeOutput(BaseModel):
"""Complete SuperClaude command output"""
command: str
status: str
timestamp: datetime
result: CommandResult
metrics: CommandMetrics
agents_activated: List[str] = Field(default_factory=list)
summary: str
errors: List[ErrorInfo] = Field(default_factory=list)
@validator('status')
def validate_status(cls, v):
valid_statuses = ['success', 'error', 'warning', 'partial']
if v not in valid_statuses:
raise ValueError(f'Invalid status: {v}')
return v
class OutputParser:
"""Parse and validate SuperClaude outputs"""
@staticmethod
def parse_json(output_str: str) -> SuperClaudeOutput:
"""Parse JSON output"""
data = json.loads(output_str)
return SuperClaudeOutput(**data)
@staticmethod
def parse_yaml(output_str: str) -> SuperClaudeOutput:
"""Parse YAML output"""
data = yaml.safe_load(output_str)
return SuperClaudeOutput(**data)
@staticmethod
def to_json(output: SuperClaudeOutput, indent: int = 2) -> str:
"""Convert to JSON string"""
return output.model_dump_json(indent=indent)
@staticmethod
def to_yaml(output: SuperClaudeOutput) -> str:
"""Convert to YAML string"""
return yaml.dump(
output.model_dump(),
sort_keys=False,
default_flow_style=False
)
@staticmethod
def to_dict(output: SuperClaudeOutput) -> Dict[str, Any]:
"""Convert to dictionary"""
return output.model_dump()
# Usage example
if __name__ == "__main__":
parser = OutputParser()
# Parse JSON output from SuperClaude
json_output = """
{
"command": "/sc:implement",
"status": "success",
...
}
"""
output = parser.parse_json(json_output)
print(f"Created {len(output.result.files_created)} files")
print(f"Quality: {output.result.quality_score * 100}%")
print(f"Cost: ${output.metrics.cost_usd:.4f}")
```
### Node.js Parser
```javascript
// superclaude-parser.js
const Joi = require('joi');
const CommandResultSchema = Joi.object({
files_created: Joi.array().items(Joi.string()).default([]),
files_modified: Joi.array().items(Joi.string()).default([]),
lines_of_code: Joi.number().integer().min(0).default(0),
tests_written: Joi.number().integer().min(0).default(0),
quality_score: Joi.number().min(0).max(1).required(),
coverage_pct: Joi.number().min(0).max(100).optional()
});
const SuperClaudeOutputSchema = Joi.object({
command: Joi.string().required(),
status: Joi.string().valid('success', 'error', 'warning', 'partial').required(),
timestamp: Joi.date().iso().required(),
result: CommandResultSchema.required(),
metrics: Joi.object({
tokens_used: Joi.number().integer().min(0).required(),
latency_ms: Joi.number().integer().min(0).required(),
cost_usd: Joi.number().min(0).required()
}).required(),
agents_activated: Joi.array().items(Joi.string()).default([]),
summary: Joi.string().required(),
errors: Joi.array().items(Joi.object()).default([])
});
class OutputParser {
static parse(jsonString) {
const data = JSON.parse(jsonString);
const { error, value } = SuperClaudeOutputSchema.validate(data);
if (error) {
throw new Error(`Validation failed: ${error.message}`);
}
return value;
}
static toJSON(output, pretty = true) {
return JSON.stringify(output, null, pretty ? 2 : 0);
}
}
module.exports = { OutputParser, SuperClaudeOutputSchema };
```
## Collaboration with Other Agents
### Receives Data From
- **All Agents**: Raw execution results
- **Metrics Analyst**: Performance metrics
- **Context Orchestrator**: Context usage stats
### Provides Data To
- **External Systems**: Structured outputs
- **CI/CD Pipelines**: Integration data
- **Metrics Analyst**: Structured metrics
- **Documentation**: API examples
### Data Exchange Protocol
```json
{
"exchange_type": "agent_output",
"source_agent": "backend-engineer",
"destination": "output-architect",
"data": {
"raw_result": {...},
"requested_format": "json",
"schema_version": "v1.0.0"
}
}
```
## Success Metrics
### Target Outcomes
- ✅ Structured Output Compliance: **78% → 95%**
- ✅ CI/CD Integration Adoption: **0% → 90%**
- ✅ API Usage: **New capability enabled**
- ✅ Developer Satisfaction: **+25%**
### Measurement Method
- Schema validation pass rate (target >99%)
- CI/CD pipeline integration count
- API client library downloads
- User feedback on format usability
## Context Engineering Strategies Applied
### Isolate Context 🔒
- Separates output structure from content
- Independent validation layer
- Format-specific transformations
- Schema-based isolation
### Write Context ✍️
- Persists output schemas
- Maintains format templates
- Stores transformation rules
### Select Context 🔍
- Chooses appropriate format
- Retrieves correct schema version
- Selects validation rules
### Compress Context 🗜️
- Optimizes output size
- Removes redundant data
- Summarizes when appropriate
## Validation Examples
### Validate Output
```bash
/sc:implement feature --output-format json --validate
```
**Validation Report**:
```
✓ Schema: superclaude-output-v1.0.0
✓ Required fields: All present
✓ Type validation: Passed
✓ Range validation: Passed
✓ Format validation: Passed
📊 Output Quality
- Files: 3 created, 2 modified ✓
- Tests: 12 written ✓
- Quality: 0.92 (Excellent) ✓
- Coverage: 87.5% (Good) ✓
✅ Output is valid and ready for integration
```
## Related Commands
- `/sc:* --output-format json` - JSON output
- `/sc:* --output-format yaml` - YAML output
- `/sc:* --validate` - Validate output schema
- `/sc:export-schema` - Export current schema
---
**Version**: 1.0.0
**Status**: Ready for Implementation
**Priority**: P0 (Critical for CI/CD integration)