Showing preview only (2,620K chars total). Download the full file or copy to clipboard to get everything.
Repository: SuperClaude-Org/SuperClaude_Framework
Branch: master
Commit: fb29cf819169
Files: 403
Total size: 2.4 MB
Directory structure:
gitextract_7b9g1o94/
├── .claude/
│ ├── settings.json
│ └── skills/
│ └── confidence-check/
│ ├── SKILL.md
│ └── confidence.ts
├── .github/
│ ├── FUNDING.yml
│ ├── PULL_REQUEST_TEMPLATE.md
│ └── workflows/
│ ├── README.md
│ ├── publish-pypi.yml
│ ├── pull-sync-framework.yml
│ ├── quick-check.yml
│ ├── readme-quality-check.yml
│ └── test.yml
├── .gitignore
├── .pre-commit-config.yaml
├── AGENTS.md
├── CHANGELOG.md
├── CLAUDE.md
├── CODEOWNERS
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── DELETION_RATIONALE.md
├── KNOWLEDGE.md
├── LICENSE
├── MANIFEST.in
├── Makefile
├── PARALLEL_INDEXING_PLAN.md
├── PLANNING.md
├── PLUGIN_INSTALL.md
├── PROJECT_INDEX.json
├── PROJECT_INDEX.md
├── PR_DOCUMENTATION.md
├── QUALITY_COMPARISON.md
├── README-ja.md
├── README-kr.md
├── README-zh.md
├── README.md
├── SECURITY.md
├── TASK.md
├── TEST_PLUGIN.md
├── VERSION
├── docs/
│ ├── Development/
│ │ ├── ARCHITECTURE.md
│ │ ├── PROJECT_STATUS.md
│ │ ├── ROADMAP.md
│ │ ├── TASKS.md
│ │ ├── hypothesis-pm-autonomous-enhancement-2025-10-14.md
│ │ ├── installation-flow-understanding.md
│ │ ├── pm-agent-ideal-workflow.md
│ │ ├── pm-agent-integration.md
│ │ ├── project-structure-understanding.md
│ │ └── tasks/
│ │ └── current-tasks.md
│ ├── PR_STRATEGY.md
│ ├── README.md
│ ├── Templates/
│ │ └── __init__.py
│ ├── agents/
│ │ └── pm-agent-guide.md
│ ├── architecture/
│ │ ├── CONTEXT_WINDOW_ANALYSIS.md
│ │ ├── MIGRATION_TO_CLEAN_ARCHITECTURE.md
│ │ ├── PHASE_1_COMPLETE.md
│ │ ├── PHASE_2_COMPLETE.md
│ │ ├── PHASE_3_COMPLETE.md
│ │ ├── PM_AGENT_COMPARISON.md
│ │ ├── SKILLS_CLEANUP.md
│ │ ├── pm-agent-auto-activation.md
│ │ └── pm-agent-responsibility-cleanup.md
│ ├── capability-mapping-v5.md
│ ├── developer-guide/
│ │ ├── README.md
│ │ ├── contributing-code.md
│ │ ├── documentation-index.md
│ │ ├── technical-architecture.md
│ │ └── testing-debugging.md
│ ├── getting-started/
│ │ ├── installation.md
│ │ └── quick-start.md
│ ├── mcp/
│ │ ├── mcp-integration-policy.md
│ │ └── mcp-optional-design.md
│ ├── memory/
│ │ ├── README.md
│ │ ├── WORKFLOW_METRICS_SCHEMA.md
│ │ ├── last_session.md
│ │ ├── next_actions.md
│ │ ├── patterns_learned.jsonl
│ │ ├── pm_context.md
│ │ ├── reflexion.jsonl.example
│ │ ├── solutions_learned.jsonl
│ │ ├── token_efficiency_validation.md
│ │ └── workflow_metrics.jsonl
│ ├── mistakes/
│ │ ├── test_database_connection-2025-11-11.md
│ │ ├── test_database_connection-2025-11-14.md
│ │ ├── test_reflexion_with_real_exception-2025-11-11.md
│ │ ├── test_reflexion_with_real_exception-2025-11-14.md
│ │ ├── unknown-2025-11-11.md
│ │ └── unknown-2025-11-14.md
│ ├── next-refactor-plan.md
│ ├── plugin-reorg.md
│ ├── pm-agent-implementation-status.md
│ ├── reference/
│ │ ├── README.md
│ │ ├── advanced-patterns.md
│ │ ├── advanced-workflows.md
│ │ ├── basic-examples.md
│ │ ├── claude-code-history-management.md
│ │ ├── commands-list.md
│ │ ├── common-issues.md
│ │ ├── comprehensive-features.md
│ │ ├── diagnostic-reference.md
│ │ ├── examples-cookbook.md
│ │ ├── integration-patterns.md
│ │ ├── mcp-server-guide.md
│ │ ├── pm-agent-autonomous-reflection.md
│ │ ├── suggested-commands.md
│ │ └── troubleshooting.md
│ ├── research/
│ │ ├── complete-python-skills-migration.md
│ │ ├── intelligent-execution-architecture.md
│ │ ├── llm-agent-token-efficiency-2025.md
│ │ ├── markdown-to-python-migration-plan.md
│ │ ├── mcp-installer-fix-summary.md
│ │ ├── parallel-execution-complete-findings.md
│ │ ├── parallel-execution-findings.md
│ │ ├── phase1-implementation-strategy.md
│ │ ├── pm-mode-performance-analysis.md
│ │ ├── pm-mode-validation-methodology.md
│ │ ├── pm-skills-migration-results.md
│ │ ├── pm_agent_roi_analysis_2025-10-21.md
│ │ ├── python_src_layout_research_20251021.md
│ │ ├── reflexion-integration-2025.md
│ │ ├── repository-understanding-proposal.md
│ │ ├── research_git_branch_integration_2025.md
│ │ ├── research_installer_improvements_20251017.md
│ │ ├── research_oss_fork_workflow_2025.md
│ │ ├── research_python_directory_naming_20251015.md
│ │ ├── research_python_directory_naming_automation_2025.md
│ │ ├── research_repository_scoped_memory_2025-10-16.md
│ │ ├── research_serena_mcp_2025-01-16.md
│ │ ├── skills-migration-test.md
│ │ └── task-tool-parallel-execution-results.md
│ ├── sessions/
│ │ └── 2025-10-14-summary.md
│ ├── testing/
│ │ ├── pm-workflow-test-results.md
│ │ └── procedures.md
│ ├── troubleshooting/
│ │ └── serena-installation.md
│ ├── user-guide/
│ │ ├── agents.md
│ │ ├── commands.md
│ │ ├── flags.md
│ │ ├── mcp-installation.md
│ │ ├── mcp-servers.md
│ │ ├── memory-system.md
│ │ ├── modes.md
│ │ └── session-management.md
│ ├── user-guide-jp/
│ │ ├── agents.md
│ │ ├── commands.md
│ │ ├── flags.md
│ │ ├── mcp-servers.md
│ │ ├── modes.md
│ │ └── session-management.md
│ ├── user-guide-kr/
│ │ ├── agents.md
│ │ ├── commands.md
│ │ ├── flags.md
│ │ ├── mcp-servers.md
│ │ ├── modes.md
│ │ └── session-management.md
│ └── user-guide-zh/
│ ├── agents.md
│ ├── commands.md
│ ├── flags.md
│ ├── mcp-servers.md
│ ├── modes.md
│ └── session-management.md
├── install.sh
├── package.json
├── plugins/
│ └── superclaude/
│ ├── __init__.py
│ ├── agents/
│ │ ├── __init__.py
│ │ ├── backend-architect.md
│ │ ├── business-panel-experts.md
│ │ ├── deep-research-agent.md
│ │ ├── deep-research.md
│ │ ├── devops-architect.md
│ │ ├── frontend-architect.md
│ │ ├── learning-guide.md
│ │ ├── performance-engineer.md
│ │ ├── pm-agent.md
│ │ ├── python-expert.md
│ │ ├── quality-engineer.md
│ │ ├── refactoring-expert.md
│ │ ├── repo-index.md
│ │ ├── requirements-analyst.md
│ │ ├── root-cause-analyst.md
│ │ ├── security-engineer.md
│ │ ├── self-review.md
│ │ ├── socratic-mentor.md
│ │ ├── system-architect.md
│ │ └── technical-writer.md
│ ├── commands/
│ │ ├── __init__.py
│ │ ├── agent.md
│ │ ├── analyze.md
│ │ ├── brainstorm.md
│ │ ├── build.md
│ │ ├── business-panel.md
│ │ ├── cleanup.md
│ │ ├── design.md
│ │ ├── document.md
│ │ ├── estimate.md
│ │ ├── explain.md
│ │ ├── git.md
│ │ ├── help.md
│ │ ├── implement.md
│ │ ├── improve.md
│ │ ├── index-repo.md
│ │ ├── index.md
│ │ ├── load.md
│ │ ├── pm.md
│ │ ├── recommend.md
│ │ ├── reflect.md
│ │ ├── research.md
│ │ ├── save.md
│ │ ├── sc.md
│ │ ├── select-tool.md
│ │ ├── spawn.md
│ │ ├── spec-panel.md
│ │ ├── task.md
│ │ ├── test.md
│ │ ├── troubleshoot.md
│ │ └── workflow.md
│ ├── core/
│ │ ├── BUSINESS_PANEL_EXAMPLES.md
│ │ ├── BUSINESS_SYMBOLS.md
│ │ ├── FLAGS.md
│ │ ├── PRINCIPLES.md
│ │ ├── RESEARCH_CONFIG.md
│ │ ├── RULES.md
│ │ └── __init__.py
│ ├── examples/
│ │ ├── __init__.py
│ │ └── deep_research_workflows.md
│ ├── hooks/
│ │ ├── __init__.py
│ │ └── hooks.json
│ ├── mcp/
│ │ ├── MCP_Chrome-DevTools.md
│ │ ├── MCP_Context7.md
│ │ ├── MCP_Magic.md
│ │ ├── MCP_Morphllm.md
│ │ ├── MCP_Playwright.md
│ │ ├── MCP_Sequential.md
│ │ ├── MCP_Serena.md
│ │ ├── MCP_Tavily.md
│ │ ├── __init__.py
│ │ └── configs/
│ │ ├── __init__.py
│ │ ├── context7.json
│ │ ├── magic.json
│ │ ├── morphllm.json
│ │ ├── playwright.json
│ │ ├── sequential.json
│ │ ├── serena-docker.json
│ │ ├── serena.json
│ │ └── tavily.json
│ ├── modes/
│ │ ├── MODE_Brainstorming.md
│ │ ├── MODE_Business_Panel.md
│ │ ├── MODE_DeepResearch.md
│ │ ├── MODE_Introspection.md
│ │ ├── MODE_Orchestration.md
│ │ ├── MODE_Task_Management.md
│ │ ├── MODE_Token_Efficiency.md
│ │ └── __init__.py
│ ├── scripts/
│ │ ├── __init__.py
│ │ ├── clean_command_names.py
│ │ └── session-init.sh
│ └── skills/
│ ├── __init__.py
│ └── confidence-check/
│ ├── SKILL.md
│ ├── __init__.py
│ └── confidence.ts
├── pyproject.toml
├── scripts/
│ ├── README.md
│ ├── ab_test_workflows.py
│ ├── analyze_workflow_metrics.py
│ ├── build_superclaude_plugin.py
│ ├── cleanup.sh
│ ├── publish.sh
│ ├── sync_from_framework.py
│ └── uninstall_legacy.sh
├── setup.py
├── skills/
│ └── confidence-check/
│ ├── SKILL.md
│ └── confidence.ts
├── src/
│ └── superclaude/
│ ├── __init__.py
│ ├── __version__.py
│ ├── agents/
│ │ ├── README.md
│ │ ├── __init__.py
│ │ ├── backend-architect.md
│ │ ├── business-panel-experts.md
│ │ ├── deep-research-agent.md
│ │ ├── deep-research.md
│ │ ├── devops-architect.md
│ │ ├── frontend-architect.md
│ │ ├── learning-guide.md
│ │ ├── performance-engineer.md
│ │ ├── pm-agent.md
│ │ ├── python-expert.md
│ │ ├── quality-engineer.md
│ │ ├── refactoring-expert.md
│ │ ├── repo-index.md
│ │ ├── requirements-analyst.md
│ │ ├── root-cause-analyst.md
│ │ ├── security-engineer.md
│ │ ├── self-review.md
│ │ ├── socratic-mentor.md
│ │ ├── system-architect.md
│ │ └── technical-writer.md
│ ├── cli/
│ │ ├── __init__.py
│ │ ├── doctor.py
│ │ ├── install_commands.py
│ │ ├── install_mcp.py
│ │ ├── install_skill.py
│ │ └── main.py
│ ├── commands/
│ │ ├── README.md
│ │ ├── __init__.py
│ │ ├── agent.md
│ │ ├── analyze.md
│ │ ├── brainstorm.md
│ │ ├── build.md
│ │ ├── business-panel.md
│ │ ├── cleanup.md
│ │ ├── design.md
│ │ ├── document.md
│ │ ├── estimate.md
│ │ ├── explain.md
│ │ ├── git.md
│ │ ├── help.md
│ │ ├── implement.md
│ │ ├── improve.md
│ │ ├── index-repo.md
│ │ ├── index.md
│ │ ├── load.md
│ │ ├── pm.md
│ │ ├── recommend.md
│ │ ├── reflect.md
│ │ ├── research.md
│ │ ├── save.md
│ │ ├── sc.md
│ │ ├── select-tool.md
│ │ ├── spawn.md
│ │ ├── spec-panel.md
│ │ ├── task.md
│ │ ├── test.md
│ │ ├── troubleshoot.md
│ │ └── workflow.md
│ ├── core/
│ │ ├── BUSINESS_PANEL_EXAMPLES.md
│ │ ├── BUSINESS_SYMBOLS.md
│ │ ├── FLAGS.md
│ │ ├── PRINCIPLES.md
│ │ ├── RESEARCH_CONFIG.md
│ │ ├── RULES.md
│ │ └── __init__.py
│ ├── examples/
│ │ ├── __init__.py
│ │ └── deep_research_workflows.md
│ ├── execution/
│ │ ├── __init__.py
│ │ ├── parallel.py
│ │ ├── reflection.py
│ │ └── self_correction.py
│ ├── hooks/
│ │ ├── README.md
│ │ ├── __init__.py
│ │ └── hooks.json
│ ├── mcp/
│ │ ├── MCP_Airis-Agent.md
│ │ ├── MCP_Chrome-DevTools.md
│ │ ├── MCP_Context7.md
│ │ ├── MCP_Magic.md
│ │ ├── MCP_Mindbase.md
│ │ ├── MCP_Morphllm.md
│ │ ├── MCP_Playwright.md
│ │ ├── MCP_Sequential.md
│ │ ├── MCP_Serena.md
│ │ ├── MCP_Tavily.md
│ │ ├── __init__.py
│ │ └── configs/
│ │ ├── __init__.py
│ │ ├── airis-agent.json
│ │ ├── context7.json
│ │ ├── magic.json
│ │ ├── mindbase.json
│ │ ├── morphllm.json
│ │ ├── playwright.json
│ │ ├── sequential.json
│ │ ├── serena-docker.json
│ │ ├── serena.json
│ │ └── tavily.json
│ ├── modes/
│ │ ├── MODE_Brainstorming.md
│ │ ├── MODE_Business_Panel.md
│ │ ├── MODE_DeepResearch.md
│ │ ├── MODE_Introspection.md
│ │ ├── MODE_Orchestration.md
│ │ ├── MODE_Task_Management.md
│ │ ├── MODE_Token_Efficiency.md
│ │ └── __init__.py
│ ├── pm_agent/
│ │ ├── __init__.py
│ │ ├── confidence.py
│ │ ├── reflexion.py
│ │ ├── self_check.py
│ │ └── token_budget.py
│ ├── pytest_plugin.py
│ ├── scripts/
│ │ ├── README.md
│ │ ├── __init__.py
│ │ ├── clean_command_names.py
│ │ └── session-init.sh
│ └── skills/
│ ├── __init__.py
│ └── confidence-check/
│ ├── SKILL.md
│ ├── __init__.py
│ └── confidence.ts
└── tests/
├── __init__.py
├── conftest.py
├── integration/
│ ├── __init__.py
│ └── test_pytest_plugin.py
└── unit/
├── __init__.py
├── test_cli_install.py
├── test_confidence.py
├── test_reflexion.py
├── test_self_check.py
└── test_token_budget.py
================================================
FILE CONTENTS
================================================
================================================
FILE: .claude/settings.json
================================================
{}
================================================
FILE: .claude/skills/confidence-check/SKILL.md
================================================
---
name: Confidence Check
description: Pre-implementation confidence assessment (≥90% required). Use before starting any implementation to verify readiness with duplicate check, architecture compliance, official docs verification, OSS references, and root cause identification.
allowed-tools: Read, Grep, Glob, WebFetch, WebSearch
---
# Confidence Check Skill
## Purpose
Prevents wrong-direction execution by assessing confidence **BEFORE** starting implementation.
**Requirement**: ≥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
## When to Use
Use this skill BEFORE implementing any task to ensure:
- No duplicate implementations exist
- Architecture compliance verified
- Official documentation reviewed
- Working OSS implementations found
- Root cause properly identified
## Confidence Assessment Criteria
Calculate confidence score (0.0 - 1.0) based on 5 checks:
### 1. No Duplicate Implementations? (25%)
**Check**: Search codebase for existing functionality
```bash
# Use Grep to search for similar functions
# Use Glob to find related modules
```
✅ Pass if no duplicates found
❌ Fail if similar implementation exists
### 2. Architecture Compliance? (25%)
**Check**: Verify tech stack alignment
- Read `CLAUDE.md`, `PLANNING.md`
- Confirm existing patterns used
- Avoid reinventing existing solutions
✅ Pass if uses existing tech stack (e.g., Supabase, UV, pytest)
❌ Fail if introduces new dependencies unnecessarily
### 3. Official Documentation Verified? (20%)
**Check**: Review official docs before implementation
- Use Context7 MCP for official docs
- Use WebFetch for documentation URLs
- Verify API compatibility
✅ Pass if official docs reviewed
❌ Fail if relying on assumptions
### 4. Working OSS Implementations Referenced? (15%)
**Check**: Find proven implementations
- Use Tavily MCP or WebSearch
- Search GitHub for examples
- Verify working code samples
✅ Pass if OSS reference found
❌ Fail if no working examples
### 5. Root Cause Identified? (15%)
**Check**: Understand the actual problem
- Analyze error messages
- Check logs and stack traces
- Identify underlying issue
✅ Pass if root cause clear
❌ Fail if symptoms unclear
## Confidence Score Calculation
```
Total = Check1 (25%) + Check2 (25%) + Check3 (20%) + Check4 (15%) + Check5 (15%)
If Total >= 0.90: ✅ Proceed with implementation
If Total >= 0.70: ⚠️ Present alternatives, ask questions
If Total < 0.70: ❌ STOP - Request more context
```
## Output Format
```
📋 Confidence Checks:
✅ No duplicate implementations found
✅ Uses existing tech stack
✅ Official documentation verified
✅ Working OSS implementation found
✅ Root cause identified
📊 Confidence: 1.00 (100%)
✅ High confidence - Proceeding to implementation
```
## Implementation Details
The TypeScript implementation is available in `confidence.ts` for reference, containing:
- `confidenceCheck(context)` - Main assessment function
- Detailed check implementations
- Context interface definitions
## ROI
**Token Savings**: Spend 100-200 tokens on confidence check to save 5,000-50,000 tokens on wrong-direction work.
**Success Rate**: 100% precision and recall in production testing.
================================================
FILE: .claude/skills/confidence-check/confidence.ts
================================================
/**
* 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";
}
}
================================================
FILE: .github/FUNDING.yml
================================================
# These are supported funding model platforms
github: NomenAK
patreon: # SuperClaude
open_collective: # Replace with a single Open Collective username
ko_fi: # superclaude
tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
liberapay: # Replace with a single Liberapay username
issuehunt: # Replace with a single IssueHunt username
lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
polar: # Replace with a single Polar username
buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
thanks_dev: # Replace with a single thanks.dev username
custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']
================================================
FILE: .github/PULL_REQUEST_TEMPLATE.md
================================================
# Pull Request
## 概要
<!-- このPRの目的を簡潔に説明 -->
## 変更内容
<!-- 主な変更点をリストアップ -->
-
## 関連Issue
<!-- 関連するIssue番号があれば記載 -->
Closes #
## チェックリスト
### Git Workflow
- [ ] 外部貢献の場合: Fork → topic branch → upstream PR の流れに従った
- [ ] コラボレーターの場合: topic branch使用（main直コミットしていない）
- [ ] `git rebase upstream/main` 済み（コンフリクトなし）
- [ ] コミットメッセージは Conventional Commits に準拠（`feat:`, `fix:`, `docs:` など）
### Code Quality
- [ ] 変更は1目的に限定（巨大PRでない、目安: ~200行差分以内）
- [ ] 既存のコード規約・パターンに従っている
- [ ] 新機能/修正には適切なテストを追加
- [ ] Lint/Format/Typecheck すべてパス
- [ ] CI/CD パイプライン成功（グリーン状態）
### Security
- [ ] シークレット・認証情報をコミットしていない
- [ ] `.gitignore` で必要なファイルを除外済み
- [ ] 破壊的変更なし／ある場合は `!` 付きコミット + MIGRATION.md 記載
### Documentation
- [ ] 必要に応じてドキュメントを更新（README, CLAUDE.md, docs/など）
- [ ] 複雑なロジックにコメント追加
- [ ] APIの変更がある場合は適切に文書化
## テスト方法
<!-- このPRの動作確認方法 -->
## スクリーンショット（該当する場合）
<!-- UIの変更がある場合はスクリーンショットを添付 -->
## 備考
<!-- レビュワーに伝えたいこと、技術的な判断の背景など -->
================================================
FILE: .github/workflows/README.md
================================================
# GitHub Actions Workflows
This directory contains CI/CD workflows for SuperClaude Framework.
## Workflows
### 1. **test.yml** - Comprehensive Test Suite
**Triggers**: Push/PR to `master` or `integration`, manual dispatch
**Jobs**:
- **test**: Run tests on Python 3.10, 3.11, 3.12
- Install UV and dependencies
- Run full test suite
- Generate coverage report (Python 3.10 only)
- Upload to Codecov
- **lint**: Run ruff linter and format checker
- **plugin-check**: Verify pytest plugin loads correctly
- **doctor-check**: Run `superclaude doctor` health check
- **test-summary**: Aggregate results from all jobs
**Status Badge**:
```markdown
[](https://github.com/SuperClaude-Org/SuperClaude_Framework/actions/workflows/test.yml)
```
### 2. **quick-check.yml** - Fast PR Feedback
**Triggers**: Pull requests to `master` or `integration`
**Jobs**:
- **quick-test**: Fast check on Python 3.10 only
- Run unit tests only (faster)
- Run linter
- Check formatting
- Verify plugin loads
- 10 minute timeout
**Purpose**: Provide rapid feedback on PRs before running full test matrix.
### 3. **publish-pypi.yml** (Existing)
**Triggers**: Manual or release tags
**Purpose**: Publish package to PyPI
### 4. **readme-quality-check.yml** (Existing)
**Triggers**: Push/PR affecting README files
**Purpose**: Validate README quality and consistency
## Local Testing
Before pushing, run these commands locally:
```bash
# Run full test suite
uv run pytest -v
# Run with coverage
uv run pytest --cov=superclaude --cov-report=term
# Run linter
uv run ruff check src/ tests/
# Check formatting
uv run ruff format --check src/ tests/
# Auto-fix formatting
uv run ruff format src/ tests/
# Verify plugin loads
uv run pytest --trace-config | grep superclaude
# Run doctor check
uv run superclaude doctor --verbose
```
## CI/CD Pipeline
```
┌─────────────────────┐
│ Push/PR Created │
└──────────┬──────────┘
│
├─────────────────────────┐
│ │
┌──────▼──────┐ ┌───────▼────────┐
│ Quick Check │ │ Full Test │
│ (PR only) │ │ Matrix │
│ │ │ │
│ • Unit tests│ │ • Python 3.10 │
│ • Lint │ │ • Python 3.11 │
│ • Format │ │ • Python 3.12 │
│ │ │ • Coverage │
│ ~2-3 min │ │ • Lint │
└─────────────┘ │ • Plugin check │
│ • Doctor check │
│ │
│ ~5-8 min │
└────────────────┘
```
## Coverage Reporting
Coverage reports are generated for Python 3.10 and uploaded to Codecov.
To view coverage locally:
```bash
uv run pytest --cov=superclaude --cov-report=html
open htmlcov/index.html
```
## Troubleshooting
### Workflow fails with "UV not found"
- UV is installed in each job via `curl -LsSf https://astral.sh/uv/install.sh | sh`
- If installation fails, check UV's status page
### Tests fail locally but pass in CI (or vice versa)
- Check Python version: `python --version`
- Reinstall dependencies: `uv pip install -e ".[dev]"`
- Clear caches: `rm -rf .pytest_cache .venv`
### Plugin not loading in CI
- Verify entry point in `pyproject.toml`: `[project.entry-points.pytest11]`
- Check plugin is installed: `uv run pytest --trace-config`
### Coverage upload fails
- This is non-blocking (fail_ci_if_error: false)
- Check Codecov token in repository secrets
## Maintenance
### Adding a New Workflow
1. Create new `.yml` file in this directory
2. Follow existing structure (checkout, setup-python, install UV)
3. Add status badge to README.md if needed
4. Document in this file
### Updating Python Versions
1. Edit `matrix.python-version` in `test.yml`
2. Update `pyproject.toml` classifiers
3. Test locally with new version first
### Modifying Test Strategy
- **quick-check.yml**: For fast PR feedback (unit tests only)
- **test.yml**: For comprehensive validation (full matrix)
## Best Practices
1. **Keep workflows fast**: Use caching, parallel jobs
2. **Fail fast**: Use `-x` flag in pytest for quick-check
3. **Clear names**: Job and step names should be descriptive
4. **Version pinning**: Pin action versions (@v4, @v5)
5. **Matrix testing**: Test on multiple Python versions
6. **Non-blocking coverage**: Don't fail on coverage upload errors
7. **Manual triggers**: Add `workflow_dispatch` for debugging
## Resources
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
- [UV Documentation](https://github.com/astral-sh/uv)
- [Pytest Documentation](https://docs.pytest.org/)
- [SuperClaude Testing Guide](../../docs/developer-guide/testing-debugging.md)
================================================
FILE: .github/workflows/publish-pypi.yml
================================================
name: Publish to PyPI
on:
# Trigger on new releases
release:
types: [published]
# Allow manual triggering
workflow_dispatch:
inputs:
target:
description: 'Publication target'
required: true
default: 'testpypi'
type: choice
options:
- testpypi
- pypi
# Restrict permissions for security
permissions:
contents: read
jobs:
build-and-publish:
name: Build and publish Python package
runs-on: ubuntu-latest
environment:
name: ${{ github.event_name == 'release' && 'pypi' || 'testpypi' }}
url: ${{ github.event_name == 'release' && 'https://pypi.org/p/SuperClaude' || 'https://test.pypi.org/p/SuperClaude' }}
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
# Fetch full history for proper version detection
fetch-depth: 0
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.11'
cache: 'pip'
- name: Install build dependencies
run: |
python -m pip install --upgrade pip
python -m pip install build twine toml
- name: Verify package structure
run: |
echo "📦 Checking package structure..."
ls -la
echo "🔍 Checking SuperClaude package..."
ls -la src/superclaude/
echo "🔍 Verifying src directory..."
ls -la src/
# Verify version consistency
echo "📋 Checking version consistency..."
python -c "
import toml
import sys
sys.path.insert(0, 'src')
# Load pyproject.toml version
with open('pyproject.toml', 'r') as f:
pyproject = toml.load(f)
pyproject_version = pyproject['project']['version']
# Load package version
from superclaude import __version__
print(f'pyproject.toml version: {pyproject_version}')
print(f'Package version: {__version__}')
if pyproject_version != __version__:
print('❌ Version mismatch!')
sys.exit(1)
else:
print('✅ Versions match')
"
- name: Clean previous builds
run: |
rm -rf dist/ build/ *.egg-info/
- name: Build package
run: |
echo "🔨 Building package..."
python -m build
echo "📦 Built files:"
ls -la dist/
- name: Validate package
run: |
echo "🔍 Validating package..."
python -m twine check dist/*
# Upload to TestPyPI for testing (manual trigger or non-release)
- name: Upload to TestPyPI
if: github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'testpypi'
uses: pypa/gh-action-pypi-publish@release/v1
with:
repository-url: https://test.pypi.org/legacy/
password: ${{ secrets.TEST_PYPI_API_TOKEN }}
print-hash: true
# Upload to production PyPI (only on releases)
- name: Upload to PyPI
if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'pypi')
uses: pypa/gh-action-pypi-publish@release/v1
with:
password: ${{ secrets.PYPI_API_TOKEN }}
print-hash: true
- name: Create deployment summary
if: always()
run: |
echo "## 📦 SuperClaude Package Deployment" >> $GITHUB_STEP_SUMMARY
echo "| Property | Value |" >> $GITHUB_STEP_SUMMARY
echo "|----------|-------|" >> $GITHUB_STEP_SUMMARY
echo "| Target | ${{ github.event_name == 'release' && 'PyPI (Production)' || github.event.inputs.target || 'TestPyPI' }} |" >> $GITHUB_STEP_SUMMARY
echo "| Trigger | ${{ github.event_name }} |" >> $GITHUB_STEP_SUMMARY
echo "| Version | $(python -c 'import sys; sys.path.insert(0, \"src\"); from superclaude import __version__; print(__version__)') |" >> $GITHUB_STEP_SUMMARY
echo "| Commit | ${{ github.sha }} |" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
if [ "${{ github.event_name }}" == "release" ]; then
echo "🎉 **Production release published to PyPI!**" >> $GITHUB_STEP_SUMMARY
echo "Install with: \`pip install SuperClaude\`" >> $GITHUB_STEP_SUMMARY
else
echo "🧪 **Test release published to TestPyPI**" >> $GITHUB_STEP_SUMMARY
echo "Test install with: \`pip install --index-url https://test.pypi.org/simple/ SuperClaude\`" >> $GITHUB_STEP_SUMMARY
fi
test-installation:
name: Test package installation
needs: build-and-publish
runs-on: ubuntu-latest
if: github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'testpypi'
steps:
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.11'
- name: Test installation from TestPyPI
run: |
echo "🧪 Testing installation from TestPyPI..."
# Wait a bit for the package to be available
sleep 30
# Install from TestPyPI
pip install --index-url https://test.pypi.org/simple/ \
--extra-index-url https://pypi.org/simple/ \
SuperClaude
# Test basic import
python -c "
import superclaude
print(f'✅ Successfully imported SuperClaude v{superclaude.__version__}')
# Test CLI entry point
import subprocess
result = subprocess.run(['SuperClaude', '--version'], capture_output=True, text=True)
print(f'✅ CLI version: {result.stdout.strip()}')
"
echo "✅ Installation test completed successfully!"
================================================
FILE: .github/workflows/pull-sync-framework.yml
================================================
name: Pull Sync from Framework
on:
schedule:
- cron: '0 */6 * * *'
workflow_dispatch:
jobs:
sync-and-isolate:
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write
steps:
- name: Checkout Plugin Repository (Target)
uses: actions/checkout@v4
with:
path: plugin-repo
- name: Check for Framework updates
id: check-updates
run: |
FRAMEWORK_HEAD=$(git ls-remote https://github.com/SuperClaude-Org/SuperClaude_Framework HEAD | cut -f1)
echo "Current framework HEAD: $FRAMEWORK_HEAD"
echo "framework-head=$FRAMEWORK_HEAD" >> $GITHUB_OUTPUT
LAST_SYNCED=""
if [ -f "plugin-repo/docs/.framework-sync-commit" ]; then
LAST_SYNCED=$(cat plugin-repo/docs/.framework-sync-commit)
echo "Last synced commit: $LAST_SYNCED"
else
echo "No previous sync state - will run sync"
fi
if [ "$FRAMEWORK_HEAD" = "$LAST_SYNCED" ] && [ "${{ github.event_name }}" != "workflow_dispatch" ]; then
echo "✅ Framework is up to date - skipping sync"
echo "has-updates=false" >> $GITHUB_OUTPUT
else
echo "🔄 Framework has updates - proceeding with sync"
echo "has-updates=true" >> $GITHUB_OUTPUT
fi
- name: Checkout Framework Repository (Source)
if: steps.check-updates.outputs.has-updates == 'true'
uses: actions/checkout@v4
with:
repository: SuperClaude-Org/SuperClaude_Framework
path: framework-src
- name: Set up Python
if: steps.check-updates.outputs.has-updates == 'true'
uses: actions/setup-python@v5
with:
python-version: '3.10'
- name: Run Transformation & Sync Logic
if: steps.check-updates.outputs.has-updates == 'true'
run: |
cd plugin-repo
python3 scripts/sync_from_framework.py
- name: Verify protected files are unchanged
if: steps.check-updates.outputs.has-updates == 'true'
working-directory: plugin-repo
run: |
# 修正: plugin.json はスクリプトによってMCPマージとして更新されるため、リストから削除しました
PROTECTED=(
"README.md" "README-ja.md" "README-zh.md"
"BACKUP_GUIDE.md" "MIGRATION_GUIDE.md" "SECURITY.md"
"CLAUDE.md" "LICENSE" ".gitignore"
".claude-plugin/marketplace.json"
"core/" "modes/"
)
VIOLATIONS=()
for path in "${PROTECTED[@]}"; do
if git diff --name-only HEAD -- "$path" | grep -q .; then
VIOLATIONS+=("$path")
fi
done
if [ ${#VIOLATIONS[@]} -gt 0 ]; then
echo "🚨 PROTECTION VIOLATION: sync modified Plugin-owned files:"
for v in "${VIOLATIONS[@]}"; do echo " • $v"; done
echo ""
echo "Fix: check SYNC_MAPPINGS in scripts/sync_from_framework.py"
exit 1
fi
echo "🔒 Protection check passed — no Plugin-owned files were modified"
- name: Save framework sync state
if: steps.check-updates.outputs.has-updates == 'true'
run: |
echo "${{ steps.check-updates.outputs.framework-head }}" > plugin-repo/docs/.framework-sync-commit
echo "✅ Saved framework commit: ${{ steps.check-updates.outputs.framework-head }}"
- name: Commit Changes to Sync Branch
if: steps.check-updates.outputs.has-updates == 'true'
id: commit-changes
working-directory: plugin-repo
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
SYNC_BRANCH="framework-sync/$(date +'%Y-%m-%d-%H%M')"
git checkout -b "$SYNC_BRANCH"
git add commands/ agents/ .claude-plugin/plugin.json plugin.json
if [ -f "docs/.framework-sync-commit" ]; then
git add -f docs/.framework-sync-commit
fi
if ! git diff --cached --quiet; then
git commit -m "chore: automated sync from framework [${{ steps.check-updates.outputs.framework-head }}]"
git push origin "$SYNC_BRANCH"
echo "has-changes=true" >> $GITHUB_OUTPUT
echo "sync-branch=$SYNC_BRANCH" >> $GITHUB_OUTPUT
else
echo "No changes detected."
echo "has-changes=false" >> $GITHUB_OUTPUT
fi
- name: Create Pull Request for Review
if: steps.commit-changes.outputs.has-changes == 'true'
working-directory: plugin-repo
env:
GH_TOKEN: ${{ github.token }}
run: |
gh pr create \
--title "chore: framework sync ${{ steps.check-updates.outputs.framework-head }}" \
--body "## Automated Framework Sync
Synced from upstream framework commit: \`${{ steps.check-updates.outputs.framework-head }}\`
**Review required before merge.** This PR was created automatically by the framework sync workflow. Please review the changes to ensure no unexpected modifications were introduced.
---
*Auto-generated by pull-sync-framework workflow*" \
--base main \
--head "${{ steps.commit-changes.outputs.sync-branch }}"
================================================
FILE: .github/workflows/quick-check.yml
================================================
name: Quick Check
on:
pull_request:
branches: [master, integration]
jobs:
quick-test:
name: Quick Test (Python 3.10)
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.10"
- name: Install UV
run: |
curl -LsSf https://astral.sh/uv/install.sh | sh
echo "$HOME/.cargo/bin" >> $GITHUB_PATH
- name: Install dependencies
run: |
uv pip install --system -e ".[dev]"
- name: Run unit tests only
run: |
pytest tests/unit/ -v --tb=short -x
- name: Run linter
run: |
ruff check src/ tests/
- name: Check formatting
run: |
ruff format --check src/ tests/
- name: Verify pytest plugin
run: |
pytest --trace-config 2>&1 | grep -q "superclaude"
- name: Summary
if: success()
run: |
echo "✅ Quick checks passed!"
echo " - Unit tests: PASSED"
echo " - Linting: PASSED"
echo " - Formatting: PASSED"
echo " - Plugin: LOADED"
================================================
FILE: .github/workflows/readme-quality-check.yml
================================================
name: README Quality Check
on:
pull_request:
paths:
- 'README*.md'
- 'Docs/**/*.md'
push:
branches: [main, master, develop]
workflow_dispatch:
permissions:
contents: read
pull-requests: write
issues: write
jobs:
readme-quality-check:
name: Multi-language README Quality Assessment
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.11'
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install requests beautifulsoup4 pyyaml
- name: Create quality checker script
run: |
cat > readme_checker.py << 'EOF'
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
SuperClaude多语言README质量检查器
检查版本同步、链接有效性、结构一致性
"""
import os
import re
import requests
import json
from pathlib import Path
from urllib.parse import urljoin
class READMEQualityChecker:
def __init__(self):
self.readme_files = ['README.md', 'README-zh.md', 'README-ja.md', 'README-kr.md']
self.results = {
'structure_consistency': [],
'link_validation': [],
'translation_sync': [],
'overall_score': 0
}
def check_structure_consistency(self):
"""检查结构一致性"""
print("🔍 检查结构一致性...")
structures = {}
for file in self.readme_files:
if os.path.exists(file):
with open(file, 'r', encoding='utf-8') as f:
content = f.read()
# 提取标题结构
headers = re.findall(r'^#{1,6}\s+(.+)$', content, re.MULTILINE)
structures[file] = len(headers)
# 比较结构差异
line_counts = [structures.get(f, 0) for f in self.readme_files if f in structures]
if line_counts:
max_diff = max(line_counts) - min(line_counts)
consistency_score = max(0, 100 - (max_diff * 5))
self.results['structure_consistency'] = {
'score': consistency_score,
'details': structures,
'status': 'PASS' if consistency_score >= 90 else 'WARN'
}
print(f"✅ 结构一致性: {consistency_score}/100")
for file, count in structures.items():
print(f" {file}: {count} headers")
def check_link_validation(self):
"""检查链接有效性"""
print("🔗 检查链接有效性...")
all_links = {}
broken_links = []
for file in self.readme_files:
if os.path.exists(file):
with open(file, 'r', encoding='utf-8') as f:
content = f.read()
# 提取所有链接
links = re.findall(r'\[([^\]]+)\]\(([^)]+)\)', content)
all_links[file] = []
for text, url in links:
link_info = {'text': text, 'url': url, 'status': 'unknown'}
# 检查本地文件链接
if not url.startswith(('http://', 'https://', '#')):
if os.path.exists(url):
link_info['status'] = 'valid'
else:
link_info['status'] = 'broken'
broken_links.append(f"{file}: {url}")
# HTTP链接检查（简化版）
elif url.startswith(('http://', 'https://')):
try:
# 只检查几个关键链接，避免过多请求
if any(domain in url for domain in ['github.com', 'pypi.org', 'npmjs.com']):
response = requests.head(url, timeout=10, allow_redirects=True)
link_info['status'] = 'valid' if response.status_code < 400 else 'broken'
else:
link_info['status'] = 'skipped'
except:
link_info['status'] = 'error'
else:
link_info['status'] = 'anchor'
all_links[file].append(link_info)
# 计算链接健康度
total_links = sum(len(links) for links in all_links.values())
broken_count = len(broken_links)
link_score = max(0, 100 - (broken_count * 10)) if total_links > 0 else 100
self.results['link_validation'] = {
'score': link_score,
'total_links': total_links,
'broken_links': broken_count,
'broken_list': broken_links[:10], # 最多显示10个
'status': 'PASS' if link_score >= 80 else 'FAIL'
}
print(f"✅ 链接有效性: {link_score}/100")
print(f" 总链接数: {total_links}")
print(f" 损坏链接: {broken_count}")
def check_translation_sync(self):
"""检查翻译同步性"""
print("🌍 检查翻译同步性...")
if not all(os.path.exists(f) for f in self.readme_files):
print("⚠️ 缺少某些README文件")
self.results['translation_sync'] = {
'score': 60,
'status': 'WARN',
'message': '缺少某些README文件'
}
return
# 检查文件修改时间
mod_times = {}
for file in self.readme_files:
mod_times[file] = os.path.getmtime(file)
# 计算时间差异（秒）
times = list(mod_times.values())
time_diff = max(times) - min(times)
# 根据时间差评分（7天内修改认为是同步的）
sync_score = max(0, 100 - (time_diff / (7 * 24 * 3600) * 20))
self.results['translation_sync'] = {
'score': int(sync_score),
'time_diff_days': round(time_diff / (24 * 3600), 2),
'status': 'PASS' if sync_score >= 80 else 'WARN',
'mod_times': {f: f"{os.path.getmtime(f):.0f}" for f in self.readme_files}
}
print(f"✅ 翻译同步性: {int(sync_score)}/100")
print(f" 最大时间差: {round(time_diff / (24 * 3600), 1)} 天")
def generate_report(self):
"""生成质量报告"""
print("\n📊 生成质量报告...")
# 计算总分
scores = [
self.results['structure_consistency'].get('score', 0),
self.results['link_validation'].get('score', 0),
self.results['translation_sync'].get('score', 0)
]
overall_score = sum(scores) // len(scores)
self.results['overall_score'] = overall_score
# 生成GitHub Actions摘要
pipe = "|"
table_header = f"{pipe} 检查项目 {pipe} 分数 {pipe} 状态 {pipe} 详情 {pipe}"
table_separator = f"{pipe}----------|------|------|------|"
table_row1 = f"{pipe} 📐 结构一致性 {pipe} {self.results['structure_consistency'].get('score', 0)}/100 {pipe} {self.results['structure_consistency'].get('status', 'N/A')} {pipe} {len(self.results['structure_consistency'].get('details', {}))} 个文件 {pipe}"
table_row2 = f"{pipe} 🔗 链接有效性 {pipe} {self.results['link_validation'].get('score', 0)}/100 {pipe} {self.results['link_validation'].get('status', 'N/A')} {pipe} {self.results['link_validation'].get('broken_links', 0)} 个损坏链接 {pipe}"
table_row3 = f"{pipe} 🌍 翻译同步性 {pipe} {self.results['translation_sync'].get('score', 0)}/100 {pipe} {self.results['translation_sync'].get('status', 'N/A')} {pipe} {self.results['translation_sync'].get('time_diff_days', 0)} 天差异 {pipe}"
summary_parts = [
"## 📊 README质量检查报告",
"",
f"### 🏆 总体评分: {overall_score}/100",
"",
table_header,
table_separator,
table_row1,
table_row2,
table_row3,
"",
"### 📋 详细信息",
"",
"**结构一致性详情:**"
]
summary = "\n".join(summary_parts)
for file, count in self.results['structure_consistency'].get('details', {}).items():
summary += f"\n- `{file}`: {count} 个标题"
if self.results['link_validation'].get('broken_links'):
summary += f"\n\n**损坏链接列表:**\n"
for link in self.results['link_validation']['broken_list']:
summary += f"\n- ❌ {link}"
summary += f"\n\n### 🎯 建议\n"
if overall_score >= 90:
summary += "✅ 质量优秀！继续保持。"
elif overall_score >= 70:
summary += "⚠️ 质量良好，有改进空间。"
else:
summary += "🚨 需要改进！请检查上述问题。"
# 写入GitHub Actions摘要
github_step_summary = os.environ.get('GITHUB_STEP_SUMMARY')
if github_step_summary:
with open(github_step_summary, 'w', encoding='utf-8') as f:
f.write(summary)
# 保存详细结果
with open('readme-quality-report.json', 'w', encoding='utf-8') as f:
json.dump(self.results, f, indent=2, ensure_ascii=False)
print("✅ 报告已生成")
# 根据分数决定退出码
return 0 if overall_score >= 70 else 1
def run_all_checks(self):
"""运行所有检查"""
print("🚀 开始README质量检查...\n")
self.check_structure_consistency()
self.check_link_validation()
self.check_translation_sync()
exit_code = self.generate_report()
print(f"\n🎯 检查完成！总分: {self.results['overall_score']}/100")
return exit_code
if __name__ == "__main__":
checker = READMEQualityChecker()
exit_code = checker.run_all_checks()
exit(exit_code)
EOF
- name: Run README quality check
run: python readme_checker.py
- name: Upload quality report
if: always()
uses: actions/upload-artifact@v4
with:
name: readme-quality-report
path: readme-quality-report.json
retention-days: 30
- name: Comment PR (if applicable)
if: github.event_name == 'pull_request' && always() && github.event.pull_request.head.repo.full_name == github.repository
uses: actions/github-script@v7
with:
script: |
const fs = require('fs');
if (fs.existsSync('readme-quality-report.json')) {
const report = JSON.parse(fs.readFileSync('readme-quality-report.json', 'utf8'));
const score = report.overall_score;
const emoji = score >= 90 ? '🏆' : score >= 70 ? '✅' : '⚠️';
const comment = `${emoji} **README质量检查结果: ${score}/100**\n\n` +
`📐 结构一致性: ${report.structure_consistency?.score || 0}/100\n` +
`🔗 链接有效性: ${report.link_validation?.score || 0}/100\n` +
`🌍 翻译同步性: ${report.translation_sync?.score || 0}/100\n\n` +
`查看详细报告请点击 Actions 标签页。`;
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: comment
});
}
================================================
FILE: .github/workflows/test.yml
================================================
name: Tests
on:
push:
branches: [master, integration]
pull_request:
branches: [master, integration]
workflow_dispatch:
jobs:
test:
name: Test on Python ${{ matrix.python-version }}
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
python-version: ["3.10", "3.11", "3.12"]
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
- name: Install UV
run: |
curl -LsSf https://astral.sh/uv/install.sh | sh
echo "$HOME/.cargo/bin" >> $GITHUB_PATH
- name: Verify UV installation
run: uv --version
- name: Install dependencies
run: |
uv pip install --system -e ".[dev]"
uv pip list --system
- name: Verify package installation
run: |
python -c "import superclaude; print(f'SuperClaude {superclaude.__version__} installed')"
python -c "import pytest_cov; print('pytest-cov is installed')"
- name: Run tests
run: |
pytest -v --tb=short --color=yes
- name: Run tests with coverage
if: matrix.python-version == '3.10'
run: |
pytest --cov=superclaude --cov-report=xml --cov-report=term
- name: Upload coverage to Codecov
if: matrix.python-version == '3.10'
uses: codecov/codecov-action@v4
with:
file: ./coverage.xml
flags: unittests
name: codecov-umbrella
fail_ci_if_error: false
lint:
name: Lint and Format Check
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.10"
- name: Install UV
run: |
curl -LsSf https://astral.sh/uv/install.sh | sh
echo "$HOME/.cargo/bin" >> $GITHUB_PATH
- name: Install dependencies
run: |
uv pip install --system -e ".[dev]"
- name: Run ruff linter
run: |
ruff check src/ tests/
- name: Check ruff formatting
run: |
ruff format --check src/ tests/
plugin-check:
name: Pytest Plugin Check
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.10"
- name: Install UV
run: |
curl -LsSf https://astral.sh/uv/install.sh | sh
echo "$HOME/.cargo/bin" >> $GITHUB_PATH
- name: Install dependencies
run: |
uv pip install --system -e ".[dev]"
- name: Verify pytest plugin loaded
run: |
pytest --trace-config 2>&1 | grep -q "superclaude" && echo "✅ Plugin loaded successfully" || (echo "❌ Plugin not loaded" && exit 1)
- name: Check available fixtures
run: |
pytest --fixtures | grep -E "(confidence_checker|self_check_protocol|reflexion_pattern|token_budget|pm_context)"
doctor-check:
name: SuperClaude Doctor Check
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.10"
- name: Install UV
run: |
curl -LsSf https://astral.sh/uv/install.sh | sh
echo "$HOME/.cargo/bin" >> $GITHUB_PATH
- name: Install dependencies
run: |
uv pip install --system -e ".[dev]"
- name: Run doctor command
run: |
superclaude doctor --verbose
test-summary:
name: Test Summary
runs-on: ubuntu-latest
needs: [test, lint, plugin-check, doctor-check]
if: always()
steps:
- name: Check test results
run: |
if [ "${{ needs.test.result }}" != "success" ]; then
echo "❌ Tests failed"
exit 1
fi
if [ "${{ needs.lint.result }}" != "success" ]; then
echo "❌ Linting failed"
exit 1
fi
if [ "${{ needs.plugin-check.result }}" != "success" ]; then
echo "❌ Plugin check failed"
exit 1
fi
if [ "${{ needs.doctor-check.result }}" != "success" ]; then
echo "❌ Doctor check failed"
exit 1
fi
echo "✅ All checks passed!"
================================================
FILE: .gitignore
================================================
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
pip-wheel-metadata/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST
# PyPI Publishing
*.whl
*.tar.gz
twine.log
.twine/
# PyInstaller
*.manifest
*.spec
# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/
# Virtual environments
venv/
env/
ENV/
env.bak/
venv.bak/
.venv/
# IDEs and editors
.vscode/
.idea/
*.swp
*.swo
*~
*.sublime-project
*.sublime-workspace
# OS specific
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db
Desktop.ini
# Logs
logs/
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Node.js (if any frontend components)
node_modules/
npm-debug.log
yarn-error.log
# Jupyter Notebook
.ipynb_checkpoints
# pyenv
.python-version
# pipenv
Pipfile.lock
# Poetry
poetry.lock
# Claude Code - only ignore user-specific files
.claude/history/
.claude/cache/
.claude/*.lock
# SuperClaude specific
.serena/
.superclaude/
*.backup
*.bak
# Project specific
Tests/
temp/
tmp/
.cache/
# Build artifacts
*.tar.gz
*.zip
*.dmg
*.pkg
*.deb
*.rpm
# Documentation builds
docs/_build/
site/
# Temporary files
*.tmp
*.temp
.temp/
# Security & API Keys
.env
.env.local
.env.*.local
.pypirc
secrets/
private/
*.key
*.pem
*.p12
*.pfx
# PyPI & Package Management
uv.lock
Pipfile.lock
poetry.lock
requirements-dev.txt
requirements-test.txt
# Development Tools
.mypy_cache/
.ruff_cache/
.black/
.isort.cfg
.flake8
pyrightconfig.json
.pylintrc
# Publishing & Release
PYPI_SETUP_COMPLETE.md
release-notes/
changelog-temp/
# Build artifacts (additional)
*.deb
*.rpm
*.dmg
*.pkg
*.msi
*.exe
# IDE & Editor specific
.vscode/settings.json
.vscode/launch.json
.idea/workspace.xml
.idea/tasks.xml
*.sublime-project
*.sublime-workspace
# System & OS
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db
Desktop.ini
$RECYCLE.BIN/
# Personal files
CRUSH.md
TODO.txt
# Development artifacts (should not be in repo)
package-lock.json
uv.lock
================================================
FILE: .pre-commit-config.yaml
================================================
# SuperClaude Framework - Pre-commit Hooks
# See https://pre-commit.com for more information
repos:
# Basic file checks
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.5.0
hooks:
- id: trailing-whitespace
exclude: '\.md$'
- id: end-of-file-fixer
- id: check-yaml
args: ['--unsafe'] # Allow custom YAML tags
- id: check-json
- id: check-toml
- id: check-added-large-files
args: ['--maxkb=1000']
- id: check-merge-conflict
- id: check-case-conflict
- id: mixed-line-ending
args: ['--fix=lf']
# Secret detection (critical for security)
- repo: https://github.com/Yelp/detect-secrets
rev: v1.4.0
hooks:
- id: detect-secrets
args:
- '--baseline'
- '.secrets.baseline'
exclude: |
(?x)^(
.*\.lock$|
.*package-lock\.json$|
.*pnpm-lock\.yaml$|
.*\.min\.js$|
.*\.min\.css$
)$
# Additional secret patterns (from CLAUDE.md)
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.5.0
hooks:
- id: detect-private-key
- id: check-yaml
name: Check for hardcoded secrets
entry: |
bash -c '
if grep -rE "(sk_live_[a-zA-Z0-9]{24,}|pk_live_[a-zA-Z0-9]{24,}|sk_test_[a-zA-Z0-9]{24,}|pk_test_[a-zA-Z0-9]{24,}|SUPABASE_SERVICE_ROLE_KEY\s*=\s*['\''\"']eyJ|SUPABASE_ANON_KEY\s*=\s*['\''\"']eyJ|NEXT_PUBLIC_SUPABASE_ANON_KEY\s*=\s*['\''\"']eyJ|OPENAI_API_KEY\s*=\s*['\''\"']sk-|TWILIO_AUTH_TOKEN\s*=\s*['\''\"'][a-f0-9]{32}|INFISICAL_TOKEN\s*=\s*['\''\"']st\.|DATABASE_URL\s*=\s*['\''\"']postgres.*@.*:.*/.*(password|passwd))" "$@" 2>/dev/null; then
echo "🚨 BLOCKED: Hardcoded secrets detected!"
echo "Replace with placeholders: your_token_here, \${VAR_NAME}, etc."
exit 1
fi
'
# Conventional Commits validation
- repo: https://github.com/compilerla/conventional-pre-commit
rev: v3.0.0
hooks:
- id: conventional-pre-commit
stages: [commit-msg]
args: []
# Markdown linting
- repo: https://github.com/igorshubovych/markdownlint-cli
rev: v0.38.0
hooks:
- id: markdownlint
args: ['--fix']
exclude: |
(?x)^(
CHANGELOG\.md|
.*node_modules.*|
.*\.min\.md$
)$
# YAML linting
- repo: https://github.com/adrienverge/yamllint
rev: v1.33.0
hooks:
- id: yamllint
args: ['-d', '{extends: default, rules: {line-length: {max: 120}, document-start: disable}}']
# Shell script linting
- repo: https://github.com/shellcheck-py/shellcheck-py
rev: v0.9.0.6
hooks:
- id: shellcheck
args: ['--severity=warning']
# Global settings
default_stages: [commit]
fail_fast: false
================================================
FILE: AGENTS.md
================================================
# Repository Guidelines
## Project Structure & Module Organization
- `src/superclaude/` holds the Python package and pytest plugin entrypoints.
- `tests/` contains Python integration/unit suites; markers map to features in `pyproject.toml`.
- `pm/`, `research/`, and `index/` house TypeScript agents with standalone `package.json`.
- `skills/` holds runtime skills (e.g., `confidence-check`); `commands/` documents scripted Claude commands.
- `docs/` provides reference packs; start with `docs/developer-guide` for workflow expectations.
## Build, Test, and Development Commands
- `make install` installs the framework editable via `uv pip install -e ".[dev]"`.
- `make test` runs `uv run pytest` across `tests/`.
- `make doctor` or `make verify` check CLI wiring and plugin health.
- `make lint` and `make format` delegate to Ruff; run after significant edits.
- TypeScript agents: inside `pm/`, run `npm install` once, then `npm test` or `npm run build`; repeat for `research/` and `index/`.
## Coding Style & Naming Conventions
- Python: 4-space indentation, Black line length 88, Ruff `E,F,I,N,W`; prefer snake_case for modules/functions and PascalCase for classes.
- Keep pytest markers explicit (`@pytest.mark.unit`, etc.) and match file names `test_*.py`.
- TypeScript: rely on project `tsconfig.json`; keep filenames kebab-case and exported classes PascalCase; align with existing PM agent modules.
- Reserve docstrings or inline comments for non-obvious orchestration; let clear naming do the heavy lifting.
## Testing Guidelines
- Default to `make test`; add `uv run pytest -m unit` to scope runs during development.
- When changes touch CLI or plugin startup, extend integration coverage in `tests/test_pytest_plugin.py`.
- Respect coverage focus on `src/superclaude` (`tool.coverage.run`); adjust configuration instead of skipping logic.
- For TypeScript agents, add Jest specs under `__tests__/*.test.ts` and keep coverage thresholds satisfied via `npm run test:coverage`.
## Commit & Pull Request Guidelines
- Follow Conventional Commits (`feat:`, `fix:`, `refactor:`) as seen in `git log`; keep present-tense summaries under ~72 chars.
- Group related file updates per commit to simplify bisects and release notes.
- Before opening a PR, run `make lint`, `make format`, and `make test`; include summaries of verification steps in the PR description.
- Reference linked issues (`Closes #123`) and, for agent workflow changes, add brief reproduction notes; screenshots only when docs change.
- Tag reviewers listed in `CODEOWNERS` when touching owned directories.
## Plugin Deployment Tips
- Use `make install-plugin` to mirror the development plugin into `~/.claude/plugins/pm-agent`; prefer `make reinstall-plugin` after local iterations.
- Validate plugin detection with `make test-plugin` before sharing artifact links or release notes.
================================================
FILE: CHANGELOG.md
================================================
# Changelog
All notable changes to SuperClaude will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
## [4.2.0] - 2026-01-18
### Added
- **AIRIS MCP Gateway** - Optional unified MCP solution with 60+ tools (#509)
- Single SSE endpoint at `localhost:9400`
- 98% token reduction through HOT/COLD tool management
- Requires Docker (optional - individual servers still supported)
- **Airis Agent and MindBase MCP servers** - New individual server options (#497)
- **Explicit command boundaries and handoff instructions** - All 30 commands now have clear scope definitions (#513)
- **Complete command reference documentation** - Comprehensive docs for all slash commands (#512)
### Fixed
- UTF-8 encoding handling for MCP command output on all platforms (#507)
### Changed
- MCP installer now offers AIRIS Gateway as recommended option (with Docker)
- Individual MCP servers remain fully supported for users without Docker
- Command documentation improved with boundaries, triggers, and next-step guidance
## [4.1.9] - 2026-01-15
### Added
- **Framework Restoration** - Complete SuperClaude framework restored from commit d4a17fc
- **30 Slash Commands** - All slash commands restored with comprehensive documentation
- **install.sh Script** - Missing installation script added (#483)
- **MCP Command** - New `superclaude mcp` command for MCP server management
- **Tavily MCP Server** - Web search integration for deep research capabilities
- **Chrome DevTools MCP** - Browser debugging and performance analysis
### Fixed
- Package distribution now includes all plugin resources
- Commands path resolution prioritizes package location
- Commands and skills properly included in MANIFEST.in
### Changed
- Synchronized translated READMEs with main README structure
- Added `__init__.py` to all packages for proper module resolution
## [4.1.5] - 2025-09-26
### Added
- Comprehensive flag documentation integrated into `/sc:help` command
- All 25 SuperClaude framework flags now discoverable from help system
- Practical usage examples and flag priority rules
### Fixed
- MCP incremental installation and auto-detection system
- Auto-detection of existing MCP servers from .claude.json and claude_desktop_config.json
- Smart server merging (existing + selected + previously installed)
- Documentation cleanup: removed non-existent commands (sc:fix, sc:simple-pix, sc:update, sc:develop, sc:modernize, sc:simple-fix)
- CLI logic to allow mcp_docs installation without server selection
### Changed
- MCP component now supports true incremental installation
- mcp_docs component auto-detects and installs documentation for all detected servers
- Improved error handling and graceful fallback for corrupted config files
- Enhanced user experience with single-source reference for all SuperClaude capabilities
## [4.1.0] - 2025-09-13
### Added
- Display author names and emails in the installer UI header.
- `is_reinstallable` flag for components to allow re-running installation.
### Fixed
- Installer now correctly installs only selected MCP servers on subsequent runs.
- Corrected validation logic for `mcp` and `mcp_docs` components to prevent incorrect failures.
- Ensured empty backup archives are created as valid tar files.
- Addressed an issue where only selected MCPs were being installed.
- Added Mithun Gowda B as an author.
- **MCP Installer:** Addressed several critical bugs in the MCP installation and update process to improve reliability.
- Corrected the npm package name for the `morphllm` server in `setup/components/mcp.py`.
- Implemented a custom installation method for the `serena` server using `uv`, as it is not an npm package.
- Resolved a `NameError` in the `update` command within `setup/cli/commands/install.py`.
- Patched a recurring "Unknown component: core" error by ensuring the component registry is initialized only once.
- Added the `claude` CLI as a formal prerequisite for MCP server management, which was previously undocumented.
### Changed
### Technical
- Prepared package for PyPI distribution
- Validated package structure and dependencies
## [4.0.7] - 2025-01-23
### Added
- Automatic update checking for PyPI and NPM packages
- `--no-update-check` flag to skip update checks
- `--auto-update` flag for automatic updates without prompting
- Environment variable `SUPERCLAUDE_AUTO_UPDATE` support
- Update notifications with colored banners showing available version
- Rate limiting to check updates once per 24 hours
- Smart installation method detection (pip/pipx/npm/yarn)
- Cache files for update check timestamps (~/.claude/.update_check and .npm_update_check)
### Fixed
- Component validation now correctly uses pipx-installed version instead of source code
### Technical
- Added `setup/utils/updater.py` for PyPI update checking logic
- Added `bin/checkUpdate.js` for NPM update checking logic
- Integrated update checks into main entry points (superclaude/__main__.py and bin/cli.js)
- Non-blocking update checks with 2-second timeout to avoid delays
### Changed
- **BREAKING**: Agent system restructured to 14 specialized agents
- **BREAKING**: Commands now use `/sc:` namespace to avoid conflicts with user custom commands
- Commands are now installed in `~/.claude/commands/sc/` subdirectory
- All 21 commands updated: `/analyze` → `/sc:analyze`, `/build` → `/sc:build`, etc.
- Automatic migration from old command locations to new `sc/` subdirectory
- **BREAKING**: Documentation reorganization - docs/ directory renamed to Guides/
### Added
- **NEW AGENTS**: 14 specialized domain agents with enhanced capabilities
- backend-architect.md, devops-architect.md, frontend-architect.md
- learning-guide.md, performance-engineer.md, python-expert.md
- quality-engineer.md, refactoring-expert.md, requirements-analyst.md
- root-cause-analyst.md, security-engineer.md, socratic-mentor.md
- **NEW MODE**: MODE_Orchestration.md for intelligent tool selection mindset (5 total behavioral modes)
- **NEW COMMAND**: `/sc:implement` for feature and code implementation (addresses v2 user feedback)
- **NEW FILE**: CLAUDE.md for project-specific Claude Code instructions
- Migration logic to move existing commands to new namespace automatically
- Enhanced uninstaller to handle both old and new command locations
- Improved command conflict prevention
- Better command organization and discoverability
- Comprehensive PyPI publishing infrastructure
- API key management during SuperClaude MCP setup
### Removed
- **BREAKING**: Removed Templates/ directory (legacy templates no longer needed)
- **BREAKING**: Removed legacy agents and replaced with enhanced 14-agent system
### Improved
- Refactored Modes and MCP documentation for concise behavioral guidance
- Enhanced project cleanup and gitignore for PyPI publishing
- Implemented uninstall and update safety enhancements
- Better agent specialization and domain expertise focus
### Technical Details
- Commands now accessible as `/sc:analyze`, `/sc:build`, `/sc:improve`, etc.
- Migration preserves existing functionality while preventing naming conflicts
- Installation process detects and migrates existing commands automatically
- Tab completion support for `/sc:` prefix to discover all SuperClaude commands
- Guides/ directory replaces docs/ for improved organization
## [4.0.6] - 2025-08-23
### Fixed
- Component validation now correctly checks .superclaude-metadata.json instead of settings.json (#291)
- Standardized version numbers across all components to 4.0.6
- Fixed agent validation to check for correct filenames (architect vs specialist/engineer)
- Fixed package.json version inconsistency (was 4.0.5)
### Changed
- Bumped version from 4.0.4 to 4.0.6 across entire project
- All component versions now synchronized at 4.0.6
- Cleaned up metadata file structure for consistency
## [4.0.4] - 2025-08-22
### Added
- **Agent System**: 13 specialized domain experts replacing personas
- **Behavioral Modes**: 4 intelligent modes for different workflows (Brainstorming, Introspection, Task Management, Token Efficiency)
- **Session Lifecycle**: /sc:load and /sc:save for cross-session persistence with Serena MCP
- **New Commands**: /sc:brainstorm, /sc:reflect, /sc:save, /sc:select-tool (21 total commands)
- **Serena MCP**: Semantic code analysis and memory management
- **Morphllm MCP**: Intelligent file editing with Fast Apply capability
- **Core Components**: Python-based framework integration (completely redesigned and implemented)
- **Templates**: Comprehensive templates for creating new components
- **Python-Ultimate-Expert Agent**: Master Python architect for production-ready code
### Changed
- Commands expanded from 16 to 21 specialized commands
- Personas replaced with 13 specialized Agents
- Enhanced MCP integration (6 servers total)
- Improved token efficiency (30-50% reduction with Token Efficiency Mode)
- Session management now uses Serena integration for persistence
- Framework structure reorganized for better modularity
### Improved
- Task management with multi-layer orchestration (TodoWrite, /task, /spawn, /loop)
- Quality gates with 8-step validation cycle
- Performance monitoring and optimization
- Cross-session context preservation
- Intelligent routing with ORCHESTRATOR.md enhancements
## [3.0.0] - 2025-07-14
### Added
- Initial release of SuperClaude v3.0
- 15 specialized slash commands for development tasks
- Smart persona auto-activation system
- MCP server integration (Context7, Sequential, Magic, Playwright)
- Unified CLI installer with multiple installation profiles
- Comprehensive documentation and user guides
- Token optimization framework
- Task management system
### Features
- **Commands**: analyze, build, cleanup, design, document, estimate, explain, git, improve, index, load, spawn, task, test, troubleshoot
- **Personas**: architect, frontend, backend, analyzer, security, mentor, refactorer, performance, qa, devops, scribe
- **MCP Servers**: Official library documentation, complex analysis, UI components, browser automation
- **Installation**: Quick, minimal, and developer profiles with component selection
================================================
FILE: CLAUDE.md
================================================
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## 🐍 Python Environment Rules
**CRITICAL**: This project uses **UV** for all Python operations. Never use `python -m`, `pip install`, or `python script.py` directly.
### Required Commands
```bash
# All Python operations must use UV
uv run pytest # Run tests
uv run pytest tests/pm_agent/ # Run specific tests
uv pip install package # Install dependencies
uv run python script.py # Execute scripts
```
## 📂 Project Structure
**Current v4.2.0 Architecture**: Python package with slash commands
```
# Claude Code Configuration (v4.2.0)
.claude/
├── settings.json # User settings
└── commands/ # Slash commands (installed via `superclaude install`)
├── pm.md
├── research.md
└── index-repo.md
# Python Package
src/superclaude/ # Pytest plugin + CLI tools
├── 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
### Essential Commands
```bash
# Setup
make dev # Install in editable mode with dev dependencies
make verify # Verify installation (package, plugin, health)
# Testing
make test # Run full test suite
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
make lint # Run ruff linter
make format # Format code with ruff
make doctor # Health check diagnostics
# MCP Servers
superclaude mcp # Interactive install (gateway default)
superclaude mcp --list # List available servers
superclaude mcp --servers airis-mcp-gateway # Install AIRIS Gateway (recommended)
superclaude mcp --servers tavily context7 # Install individual servers
# Plugin Packaging
make build-plugin # Build plugin artefacts into dist/
make sync-plugin-repo # Sync artefacts into ../SuperClaude_Plugin
# Maintenance
make clean # Remove build artifacts
```
## 📦 Core Architecture
### Pytest Plugin (Auto-loaded)
Registered via `pyproject.toml` entry point, automatically available after installation.
**Fixtures**: `confidence_checker`, `self_check_protocol`, `reflexion_pattern`, `token_budget`, `pm_context`
**Auto-markers**:
- Tests in `/unit/` → `@pytest.mark.unit`
- Tests in `/integration/` → `@pytest.mark.integration`
**Custom markers**: `@pytest.mark.confidence_check`, `@pytest.mark.self_check`, `@pytest.mark.reflexion`
### PM Agent - Three Core Patterns
**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
**2. SelfCheckProtocol** (src/superclaude/pm_agent/self_check.py)
- Post-implementation evidence-based validation
- No speculation - verify with tests/docs
**3. ReflexionPattern** (src/superclaude/pm_agent/reflexion.py)
- Error learning and prevention
- Cross-session pattern matching
### Parallel Execution
**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]
### Slash Commands (v4.2.0)
- Install via: `pipx install superclaude && superclaude install`
- Commands installed to: `~/.claude/commands/`
- Available: `/pm`, `/research`, `/index-repo`, and 27 others
> **Note**: TypeScript plugin system planned for v5.0 ([#419](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues/419))
## 🧪 Testing with PM Agent
### Example Test with Markers
```python
@pytest.mark.confidence_check
def test_feature(confidence_checker):
"""Pre-execution confidence check - skips if < 70%"""
context = {"test_name": "test_feature", "has_official_docs": True}
assert confidence_checker.assess(context) >= 0.7
@pytest.mark.self_check
def test_implementation(self_check_protocol):
"""Post-implementation validation with evidence"""
implementation = {"code": "...", "tests": [...]}
passed, issues = self_check_protocol.validate(implementation)
assert passed, f"Validation failed: {issues}"
@pytest.mark.reflexion
def test_error_learning(reflexion_pattern):
"""If test fails, reflexion records for future prevention"""
pass
@pytest.mark.complexity("medium") # simple: 200, medium: 1000, complex: 2500
def test_with_budget(token_budget):
"""Token budget allocation"""
assert token_budget.limit == 1000
```
## 🌿 Git Workflow
**Branch structure**: `master` (production) ← `integration` (testing) ← `feature/*`, `fix/*`, `docs/*`
**Standard workflow**:
1. Create branch from `integration`: `git checkout -b feature/your-feature`
2. Develop with tests: `uv run pytest`
3. Commit: `git commit -m "feat: description"` (conventional commits)
4. Merge to `integration` → validate → merge to `master`
**Current branch**: See git status in session start output
### Parallel Development with Git Worktrees
**CRITICAL**: When running multiple Claude Code sessions in parallel, use `git worktree` to avoid conflicts.
```bash
# Create worktree for integration branch
cd ~/github/SuperClaude_Framework
git worktree add ../SuperClaude_Framework-integration integration
# Create worktree for feature branch
git worktree add ../SuperClaude_Framework-feature feature/pm-agent
```
**Benefits**:
- Run Claude Code sessions on different branches simultaneously
- No branch switching conflicts
- Independent working directories
- Parallel development without state corruption
**Usage**:
- Session A: Open `~/github/SuperClaude_Framework/` (current branch)
- Session B: Open `~/github/SuperClaude_Framework-integration/` (integration)
- Session C: Open `~/github/SuperClaude_Framework-feature/` (feature branch)
**Cleanup**:
```bash
git worktree remove ../SuperClaude_Framework-integration
```
## 📝 Key Documentation Files
**PLANNING.md** - Architecture, design principles, absolute rules
**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
### 1. Evidence-Based Development
**Never guess** - verify with official docs (Context7 MCP, WebFetch, WebSearch) before implementation.
### 2. Confidence-First Implementation
Check confidence BEFORE starting: ≥90% proceed, 70-89% present alternatives, <70% ask questions.
### 3. Parallel-First Execution
Use **Wave → Checkpoint → Wave** pattern (3.5x faster). Example: `[Read files in parallel]` → Analyze → `[Edit files in parallel]`
### 4. Token Efficiency
- Simple (typo): 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
## 🔧 MCP Server Integration
**Recommended**: Use **airis-mcp-gateway** for unified MCP management.
```bash
superclaude mcp # Interactive install, gateway is default (requires Docker)
```
**Gateway Benefits**: 60+ tools, 98% token reduction, single SSE endpoint, Web UI
**High Priority Servers** (included in gateway):
- **Tavily**: Web search (Deep Research)
- **Context7**: Official documentation (prevent hallucination)
- **Sequential**: Token-efficient reasoning (30-50% reduction)
- **Serena**: Session persistence
- **Mindbase**: Cross-session learning
**Optional**: Playwright (browser automation), Magic (UI components), Chrome DevTools (performance)
**Usage**: TypeScript plugins and Python pytest plugin can call MCP servers. Always prefer MCP tools over speculation for documentation/research.
## 🚀 Development & Installation
### Current Installation Method (v4.2.0)
**Standard Installation**:
```bash
# Option 1: pipx (recommended)
pipx install superclaude
superclaude install
# Option 2: Direct from repo
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
./install.sh
```
**Development Mode**:
```bash
# Install in editable mode
make dev
# Run tests
make test
# Verify installation
make verify
```
### Plugin System (v5.0 - Not Yet Available)
The TypeScript plugin system (`.claude-plugin/`, marketplace) is planned for v5.0.
See `docs/plugin-reorg.md` for details.
## 📊 Package Information
**Package name**: `superclaude`
**Version**: 4.2.0
**Python**: >=3.10
**Build system**: hatchling (PEP 517)
**Entry points**:
- CLI: `superclaude` command
- Pytest plugin: Auto-loaded as `superclaude`
**Dependencies**:
- pytest>=7.0.0
- click>=8.0.0
- rich>=13.0.0
================================================
FILE: CODEOWNERS
================================================
* @NomenAK @mithun50
================================================
FILE: CODE_OF_CONDUCT.md
================================================
# Code of Conduct
## 🤝 Our Commitment
SuperClaude Framework is committed to fostering an inclusive, professional, and collaborative community focused on advancing AI-assisted software development. We welcome contributors of all backgrounds, experience levels, and perspectives to participate in building better development tools and workflows.
**Our Mission**: Create a supportive environment where software developers can learn, contribute, and innovate together while maintaining the highest standards of technical excellence and professional conduct.
**Core Values**: Technical merit, inclusive collaboration, continuous learning, and practical utility guide all community interactions and decisions.
## 🎯 Our Standards
### Positive Behavior ✅
**Professional Communication:**
- Use clear, technical language appropriate for software development discussions
- Provide constructive feedback with specific examples and actionable suggestions
- Ask clarifying questions before making assumptions about requirements or implementations
- Share knowledge and experience to help others learn and improve
**Collaborative Development:**
- Focus on technical merit and project goals in all discussions and decisions
- Respect different experience levels and provide mentorship opportunities
- Acknowledge contributions and give credit where appropriate
- Participate in code review with constructive, educational feedback
**Inclusive Participation:**
- Welcome newcomers with patience and helpful guidance
- Use inclusive language that considers diverse backgrounds and perspectives
- Provide context and explanations for technical decisions and recommendations
- Create learning opportunities through documentation and examples
**Quality Focus:**
- Maintain high standards for code quality, documentation, and user experience
- Prioritize user value and practical utility in feature discussions
- Support evidence-based decision making with testing and validation
- Contribute to long-term project sustainability and maintainability
**Community Building:**
- Participate in discussions with good faith and positive intent
- Share workflows, patterns, and solutions that benefit the community
- Help others troubleshoot issues and learn framework capabilities
- Celebrate community achievements and milestones
### Unacceptable Behavior ❌
**Disrespectful Communication:**
- Personal attacks, insults, or derogatory comments about individuals or groups
- Harassment, trolling, or deliberately disruptive behavior
- Discriminatory language or behavior based on personal characteristics
- Public or private harassment of community members
**Unprofessional Conduct:**
- Deliberately sharing misinformation or providing harmful technical advice
- Spamming, advertising unrelated products, or promotional content
- Attempting to manipulate discussions or decision-making processes
- Violating intellectual property rights or licensing terms
**Destructive Behavior:**
- Sabotaging project infrastructure, code, or community resources
- Intentionally introducing security vulnerabilities or malicious code
- Sharing private or confidential information without permission
- Deliberately disrupting project operations or community activities
**Technical Misconduct:**
- Submitting plagiarized code or claiming others' work as your own
- Knowingly providing incorrect or misleading technical information
- Ignoring security best practices or introducing unnecessary risks
- Circumventing established review processes or quality gates
**Community Violations:**
- Violating project licensing terms or contributor agreements
- Using community platforms for commercial promotion without permission
- Creating multiple accounts to circumvent moderation or bans
- Coordinating attacks or harassment campaigns against community members
## 📋 Our Responsibilities
### Project Maintainers
**Community Standards Enforcement:**
- Monitor community interactions and maintain professional discussion standards
- Address code of conduct violations promptly and fairly
- Provide clear explanations for moderation decisions and consequences
- Ensure consistent application of community standards across all platforms
**Technical Leadership:**
- Maintain project quality standards through code review and architectural guidance
- Make final decisions on technical direction and feature priorities
- Ensure security best practices and responsible disclosure handling
- Coordinate release management and compatibility maintenance
**Inclusive Community Building:**
- Welcome new contributors and provide onboarding guidance
- Facilitate constructive discussions and help resolve technical disagreements
- Recognize and celebrate community contributions appropriately
- Create opportunities for skill development and knowledge sharing
**Transparency and Communication:**
- Communicate project decisions and rationale clearly to the community
- Provide regular updates on project status, roadmap, and priorities
- Respond to community questions and concerns in a timely manner
- Maintain open and accessible communication channels
**Conflict Resolution:**
- Address interpersonal conflicts with fairness and professionalism
- Mediate technical disagreements and help find consensus solutions
- Escalate serious violations to appropriate enforcement mechanisms
- Document decisions and maintain consistent enforcement policies
### Community Members
**Technical Contribution Quality:**
- Follow established coding standards, testing requirements, and documentation guidelines
- Participate in code review process constructively and responsively
- Ensure contributions align with project goals and architectural principles
- Test changes thoroughly and provide clear descriptions of functionality
**Professional Communication:**
- Communicate respectfully and professionally in all community interactions
- Provide helpful feedback and ask clarifying questions when needed
- Share knowledge and help others learn framework capabilities
- Report technical issues with clear reproduction steps and relevant context
**Community Participation:**
- Read and follow project documentation, including contributing guidelines
- Respect maintainer decisions and project direction while providing constructive input
- Help newcomers learn the framework and contribute effectively
- Participate in discussions with good faith and focus on technical merit
**Responsible Behavior:**
- Report code of conduct violations through appropriate channels
- Respect intellectual property rights and licensing requirements
- Maintain confidentiality of private information and security-sensitive details
- Use community resources responsibly and avoid disruptive behavior
**Continuous Learning:**
- Stay updated on project changes, best practices, and security considerations
- Seek feedback on contributions and incorporate suggestions for improvement
- Share experiences and patterns that benefit the broader community
- Contribute to documentation and educational resources when possible
## 🚨 Enforcement
### Reporting Issues
**Reporting Channels:**
**Primary Contact:**
- **Email**: anton.knoery@gmail.com (monitored by conduct team)
- **Response Time**: 48-72 hours for initial acknowledgment
- **Confidentiality**: All reports treated with appropriate discretion
**Alternative Channels:**
- **GitHub Issues**: For public discussion of community standards and policies
- **Direct Contact**: Individual maintainer contact for urgent situations
- **Anonymous Reporting**: Anonymous form available for sensitive situations
**What to Include in Reports:**
- Clear description of the incident or behavior
- Date, time, and location (platform/channel) where incident occurred
- Names of individuals involved (if known and relevant)
- Screenshots, links, or other evidence (if available)
- Impact on you or the community
- Previous related incidents (if applicable)
**Reporting Template:**
```
**Incident Description:**
[Clear summary of what occurred]
**Date/Time/Location:**
[When and where the incident took place]
**Individuals Involved:**
[Names or usernames of people involved]
**Evidence:**
[Links, screenshots, or other supporting information]
**Impact:**
[How this affected you or the community]
**Additional Context:**
[Any other relevant information or previous incidents]
```
**Support for Reporters:**
- Guidance on documentation and evidence collection
- Regular updates on investigation progress
- Protection from retaliation or further harassment
- Resources for additional support if needed
### Investigation Process
**Investigation Process:**
**Initial Response (24-48 hours):**
- Acknowledge receipt of report to reporter
- Review submitted evidence and documentation
- Identify conduct team members for investigation (avoiding conflicts of interest)
- Take immediate action if required to prevent ongoing harm
**Investigation Phase (3-7 days):**
- Gather additional information and evidence as needed
- Interview relevant parties while maintaining confidentiality
- Consult with other maintainers and conduct team members
- Review similar past incidents for consistency in handling
**Decision and Response (7-14 days from initial report):**
- Determine whether code of conduct violation occurred
- Decide on appropriate consequences based on severity and impact
- Communicate decision to reporter and involved parties
- Implement consequences and monitoring as appropriate
**Timeline Extensions:**
- Complex cases may require additional investigation time
- Reporter notified of any delays with updated timeline
- Urgent cases prioritized for faster resolution
- External consultation may be sought for serious violations
**Documentation and Follow-up:**
- All incidents documented for pattern recognition and consistency
- Follow-up communication to ensure resolution effectiveness
- Policy updates if investigation reveals gaps or improvements needed
- Community notification for serious violations affecting project safety
**Confidentiality:**
- Investigation details kept confidential to protect all parties
- Information shared only with conduct team and relevant maintainers
- Public disclosure only when necessary for community safety
- Reporter identity protected unless they consent to disclosure
### Possible Consequences
**Consequence Levels:**
**Level 1: Education and Guidance**
- **For**: Minor violations, first-time issues, misunderstandings
- **Actions**: Private conversation, resource sharing, clarification of expectations
- **Examples**: Inappropriate language, unclear communication, minor disruption
- **Monitoring**: Informal follow-up to ensure improvement
**Level 2: Formal Warning**
- **For**: Repeated minor violations, moderate behavioral issues
- **Actions**: Written warning, specific behavior changes required, defined monitoring period
- **Examples**: Continued disrespectful communication, ignoring feedback, minor harassment
- **Monitoring**: Structured check-ins and progress evaluation
**Level 3: Temporary Restrictions**
- **For**: Serious violations, repeated warnings ignored, significant disruption
- **Actions**: Temporary ban from specific platforms, contribution restrictions, supervision required
- **Duration**: 1-30 days depending on severity
- **Examples**: Personal attacks, deliberate misinformation, persistent harassment
**Level 4: Long-term Suspension**
- **For**: Severe violations, pattern of harmful behavior, community impact
- **Actions**: Extended ban from all community platforms and contribution activities
- **Duration**: 3-12 months with defined rehabilitation requirements
- **Examples**: Serious harassment, security violations, malicious code submission
**Level 5: Permanent Ban**
- **For**: Extreme violations, threats to community safety, legal violations
- **Actions**: Permanent removal from all community spaces and activities
- **No Appeals**: Reserved for the most serious violations only
- **Examples**: Doxxing, threats of violence, serious legal violations, coordinated attacks
**Appeals Process:**
- Available for Levels 2-4 within 30 days of decision
- Must include acknowledgment of behavior and improvement plan
- Reviewed by different conduct team members than original decision
- Appeals focus on process fairness and proportionality of consequences
## 🌍 Scope
**GitHub Repositories:**
- SuperClaude Framework main repository and all related repositories
- Issues, pull requests, discussions, and code review interactions
- Repository wikis, documentation, and project boards
- Release notes, commit messages, and repository metadata
**Communication Platforms:**
- GitHub Discussions and Issues for project-related communication
- Any official SuperClaude social media accounts or announcements
- Community forums, chat channels, or messaging platforms
- Video calls, meetings, or webinars related to the project
**Events and Conferences:**
- SuperClaude-sponsored events, meetups, or conference presentations
- Community workshops, training sessions, or educational events
- Online events, webinars, or live streams featuring SuperClaude
- Informal gatherings or meetups organized by community members
**External Platforms:**
- Stack Overflow, Reddit, or other platforms when discussing SuperClaude
- Social media interactions related to the project or community
- Blog posts, articles, or publications about SuperClaude Framework
- Professional networking platforms when representing the community
**Private Communications:**
- Direct messages between community members about project matters
- Email communications related to project contributions or support
- Private discussions about technical issues or collaboration
- Mentorship relationships formed through community participation
**Representation Guidelines:**
When representing SuperClaude Framework in any capacity:
- Professional behavior expected regardless of platform or context
- Community standards apply even in informal settings
- Consider impact on project reputation and community relationships
- Seek guidance from maintainers when uncertain about representation
## 💬 Guidelines for Healthy Discussion
**Technical Discussion Best Practices:**
**Focus on Merit:**
- Base arguments on technical evidence, user value, and project goals
- Provide specific examples, benchmarks, or test results to support positions
- Consider multiple perspectives and trade-offs in complex decisions
- Acknowledge when you lack expertise and seek input from domain experts
**Constructive Disagreement:**
- Disagree with ideas and approaches, not individuals
- Explain reasoning clearly and provide alternative solutions
- Ask clarifying questions to understand different viewpoints
- Find common ground and build consensus through collaboration
**Knowledge Sharing:**
- Share context and background for technical decisions
- Explain concepts clearly for community members with different experience levels
- Provide links to documentation, examples, or external resources
- Contribute to collective understanding through detailed explanations
**Decision Making:**
- Respect maintainer authority for final technical decisions
- Provide input early in the decision process rather than after implementation
- Accept decisions gracefully while maintaining option for future discussion
- Focus on implementation quality and user impact over personal preferences
**Community Discussion Guidelines:**
**Inclusive Participation:**
- Welcome newcomers and provide context for ongoing discussions
- Use clear language and avoid excessive jargon or insider references
- Provide multiple ways to participate (writing, examples, testing, etc.)
- Encourage diverse perspectives and experience sharing
**Productive Conversations:**
- Stay on topic and maintain focus on actionable outcomes
- Break complex discussions into smaller, manageable topics
- Summarize long discussions and highlight key decisions or next steps
- Use threading and clear subject lines to organize related discussions
## 🎓 Educational Approach
**Educational Philosophy:**
SuperClaude Framework prioritizes education and growth over punishment when addressing community issues. We believe most conflicts arise from misunderstandings, different experience levels, or lack of context rather than malicious intent.
**Learning-Focused Enforcement:**
- First response focuses on education and clarification of expectations
- Provide resources and examples for better community participation
- Connect community members with mentors and learning opportunities
- Emphasize skill development and professional growth through participation
**Conflict Resolution Approach:**
- Address underlying causes of conflicts rather than just symptoms
- Facilitate direct communication between parties when appropriate
- Provide mediation and guidance for technical and interpersonal disagreements
- Focus on finding solutions that benefit the entire community
**Progressive Development:**
- Recognize that community participation skills develop over time
- Provide scaffolding and support for newcomers learning professional communication
- Create opportunities for community members to learn from mistakes
- Celebrate growth and improvement in community participation
**Restorative Practices:**
- Encourage acknowledgment of harm and genuine efforts to make amends
- Focus on rebuilding trust and relationships after conflicts
- Provide pathways for community members to contribute positively after violations
- Balance accountability with opportunities for redemption and growth
**Community Learning:**
- Use conflicts as learning opportunities for the entire community
- Share lessons learned (while protecting individual privacy)
- Update policies and practices based on community experience
- Build collective wisdom about effective collaboration and communication
## 📞 Contact Information
### Conduct Team
**Conduct Team:**
- **Primary Contact**: anton.knoery@gmail.com
- **Team Composition**: Selected maintainers and community members with training in conflict resolution
- **Response Time**: 48-72 hours for initial acknowledgment
- **Availability**: Monitored continuously with escalation procedures for urgent issues
**Team Responsibilities:**
- Review and investigate code of conduct violation reports
- Provide guidance on community standards and policy interpretation
- Mediate conflicts and facilitate resolution between community members
- Recommend policy updates based on community needs and experiences
**Expertise Areas:**
- **Technical Guidance**: Code review standards, contribution quality, project architecture
- **Community Building**: Inclusive participation, mentorship, conflict resolution
- **Security**: Vulnerability reporting, responsible disclosure, safety protocols
- **Legal Compliance**: Licensing, intellectual property, harassment prevention
**Confidentiality and Impartiality:**
- All conduct team members trained in confidential information handling
- Recusal procedures for cases involving personal relationships or conflicts of interest
- External consultation available for complex cases requiring specialized expertise
- Regular training updates on best practices for community management
**Contact Preferences:**
- **Email**: anton.knoery@gmail.com for all formal reports and inquiries
- **Anonymous**: Anonymous reporting form available for sensitive situations
- **Urgent**: Emergency contact procedures for immediate safety concerns
- **Follow-up**: Scheduled check-ins for ongoing cases and policy discussions
### Project Leadership
**Project Leadership:**
- **Maintainers**: @SuperClaude-Org maintainer team on GitHub
- **Issues**: GitHub Issues with `conduct` or `community` labels for public policy discussions
- **Email**: anton.knoery@gmail.com for general leadership questions
**Leadership Responsibilities:**
- **Policy Development**: Creating and updating community standards and enforcement procedures
- **Strategic Direction**: Ensuring community policies align with project goals and values
- **Resource Allocation**: Providing support and resources for community management
- **Final Appeals**: Serving as final authority for serious enforcement decisions
**Escalation Procedures:**
- **Level 1**: Conduct team handles day-to-day community management
- **Level 2**: Project maintainers involved for policy questions and serious violations
- **Level 3**: Project leadership council for appeals and policy changes
- **External**: Legal counsel or external mediation for extreme cases
**Policy Questions:**
- **Community Standards**: Interpretation of code of conduct and enforcement guidelines
- **Inclusion Practices**: Guidance on inclusive participation and accessibility
- **Technical Standards**: Integration of community standards with technical contribution requirements
- **External Relations**: Representation of community standards in external partnerships
**Public Communication:**
- **Transparency**: Regular updates on community health and policy effectiveness
- **Education**: Resources and training for community members and contributors
- **Accountability**: Public reporting on enforcement actions and policy changes
- **Feedback**: Open channels for community input on policies and procedures
## 🙏 Acknowledgments
**Code of Conduct Sources:**
This code of conduct draws inspiration from several established community standards and best practices:
**Primary Sources:**
- **Contributor Covenant**: Industry-standard framework for open source community standards
- **Python Community Code of Conduct**: Emphasis on technical excellence and inclusive participation
- **Mozilla Community Participation Guidelines**: Focus on healthy contribution and conflict resolution
- **GitHub Community Guidelines**: Platform-specific behavior standards and enforcement practices
**Professional Standards:**
- **ACM Code of Ethics**: Professional computing and software development standards
- **IEEE Code of Ethics**: Engineering ethics and professional responsibility
- **Software Engineering Body of Knowledge**: Best practices for collaborative software development
- **Open Source Initiative**: Community building and governance best practices
**Academic Research:**
- **Diversity and Inclusion in Open Source**: Research on effective inclusive community practices
- **Conflict Resolution in Technical Communities**: Evidence-based approaches to technical disagreement
- **Psychological Safety in Teams**: Creating environments for effective collaboration and learning
- **Community of Practice Theory**: Building knowledge-sharing communities
**Legal and Compliance:**
- **Anti-Harassment Laws**: Applicable legal standards for workplace and community behavior
- **International Human Rights Standards**: Universal principles for respectful interaction
- **Platform Terms of Service**: Compliance with GitHub and other platform community standards
- **Accessibility Guidelines**: Ensuring inclusive participation for diverse abilities and backgrounds
## 📚 Additional Resources
**Community Building Resources:**
**Inclusive Participation:**
- [Mozilla's Inclusion and Diversity Guide](https://wiki.mozilla.org/Inclusion) - Practical strategies for inclusive communities
- [GitHub's Open Source Guide](https://opensource.guide/) - Community building and maintenance
- [CHAOSS Diversity & Inclusion Metrics](https://chaoss.community/) - Measuring community health and inclusion
- [Turing Way Community Handbook](https://the-turing-way.netlify.app/) - Collaborative research community practices
**Conflict Resolution:**
- [Contributor Covenant Enforcement Guide](https://www.contributor-covenant.org/enforcement/) - Best practices for code of conduct enforcement
- [Restorative Justice in Tech](https://www.restorativejusticefortech.com/) - Alternative approaches to community conflict
- [Crucial Conversations](https://cruciallearning.com/) - Professional communication and difficult conversations
- [Harvard Negotiation Project](https://www.pon.harvard.edu/) - Interest-based negotiation and conflict resolution
**Bystander Intervention:**
- **Recognize**: Identify when community standards are being violated or when someone needs support
- **Assess**: Evaluate the situation and determine the most appropriate response
- **Act**: Intervene directly, seek help from moderators, or provide support to affected parties
- **Follow Up**: Check on involved parties and report incidents to appropriate authorities
**Professional Development:**
- [Software Engineering Ethics](https://ethics.acm.org/) - Professional standards for computing professionals
- [IEEE Computer Society Code of Ethics](https://www.computer.org/code-of-ethics) - Technical professional standards
- [Open Source Citizenship](https://github.com/opensourcecitizenship/opensourcecitizenship) - Responsible open source participation
- [Tech Workers Coalition](https://techworkerscoalition.org/) - Collective action and professional responsibility
**Educational Resources:**
- [Unconscious Bias Training](https://www.google.com/search?q=unconscious+bias+training) - Understanding and addressing implicit bias
- [Active Bystander Training](https://www.ihollaback.org/) - Intervention strategies for harassment and discrimination
- [Psychological Safety](https://rework.withgoogle.com/guides/understanding-team-effectiveness/) - Creating safe environments for collaboration
---
**Policy Maintenance:**
**Last Updated**: December 2024 (SuperClaude Framework v4.0)
**Next Review**: June 2025 (Semi-annual review cycle)
**Version**: 4.1.5 (Updated for v4 community structure and governance)
**Review Schedule:**
- **Semi-Annual Reviews**: Policy effectiveness assessment and community feedback integration
- **Incident-Based Updates**: Policy updates following significant enforcement actions or lessons learned
- **Community-Driven Changes**: Updates based on community proposals and feedback
- **Legal Compliance Updates**: Updates to maintain compliance with changing legal standards
**Change Process:**
- **Minor Updates**: Clarifications, contact updates, and resource additions
- **Major Updates**: Substantial policy changes with community discussion and feedback period
- **Emergency Updates**: Critical changes for community safety with immediate implementation
- **Community Input**: Regular solicitation of feedback through surveys and open discussions
**Community Acknowledgments:**
SuperClaude Framework's inclusive and professional community culture benefits from the active participation of contributors who embody these values in their daily interactions and technical contributions.
**Community Contributors:**
- Community members who model professional communication and inclusive participation
- Contributors who provide mentorship and support to newcomers and fellow developers
- Individuals who report issues constructively and help maintain community standards
- Advocates who promote the framework and community in external venues
**Positive Impact Recognition:**
- [GitHub Contributors](https://github.com/SuperClaude-Org/SuperClaude_Framework/graphs/contributors) - Technical and community contributions
- Community discussions highlight helpful guidance, mentorship, and collaborative problem-solving
- Regular appreciation for inclusive behavior and professional communication
- Annual community recognition for outstanding contributions to community culture
**Growing Community:**
The SuperClaude community continues to grow through shared commitment to technical excellence, inclusive collaboration, and continuous learning. Community-focused contributions, from welcoming newcomers to facilitating productive discussions, strengthen the environment for all participants.
**Join Our Community:**
Whether you're contributing code, improving documentation, helping others learn, or participating in discussions, your commitment to professional and inclusive behavior helps build a better software development community for everyone. Every positive interaction contributes to our collective success and the advancement of AI-assisted development tools.
================================================
FILE: CONTRIBUTING.md
================================================
# Contributing to SuperClaude Framework
SuperClaude Framework transforms Claude Code into a structured development platform through behavioral instruction injection and intelligent workflow orchestration. We welcome contributions that enhance the framework's capabilities, improve documentation, and expand the ecosystem of specialized agents and MCP server integrations.
**Project Mission**: Enable systematic software development workflows with automated expert coordination, quality gates, and session persistence for Claude Code users.
**Community Approach**: Open development with focus on practical utility, educational value, and professional development workflows. All contributions undergo review to ensure alignment with framework principles and quality standards.
## 🎯 Ways to Contribute
### 🐛 Bug Reports
**Before Reporting:**
- Search existing issues to avoid duplicates
- Test with latest SuperClaude version
- Verify issue isn't covered in [Troubleshooting Guide](docs/Reference/troubleshooting.md)
**Required Information:**
- SuperClaude version: `SuperClaude --version`
- Operating system and version
- Claude Code version: `claude --version`
- Python version: `python3 --version`
- Exact steps to reproduce the issue
- Expected vs actual behavior
- Error messages or logs
- Minimal code example (if applicable)
**Good Bug Report Example:**
```
**Environment:**
- SuperClaude: 4.1.5
- OS: Ubuntu 22.04
- Claude Code: 1.5.2
- Python: 3.9.7
**Issue:** `/sc:implement` command fails with ModuleNotFoundError
**Steps to Reproduce:**
1. Run `SuperClaude install --components core`
2. Execute `/sc:implement "user login"`
3. Error appears: ModuleNotFoundError: No module named 'requests'
**Expected:** Command should execute implementation workflow
**Actual:** Import error prevents execution
```
**Issue Labels:**
- `bug`: Confirmed software defects
- `enhancement`: Feature improvements
- `documentation`: Documentation issues
- `question`: Support requests
- `good-first-issue`: Beginner-friendly contributions
### 💡 Feature Requests
**Feature Evaluation Criteria:**
- Aligns with SuperClaude's systematic development workflow mission
- Provides clear utility for software development tasks
- Integrates well with existing command/agent/mode architecture
- Maintains framework simplicity and discoverability
**High-Priority Features:**
- New specialized agents for emerging domains (mobile, ML, blockchain)
- Additional MCP server integrations for enhanced capabilities
- Workflow automation improvements and quality gates
- Cross-session project management enhancements
**Feature Request Template:**
```markdown
**Feature Description:**
Clear summary of the proposed functionality
**Use Case:**
Specific development scenarios where this feature adds value
**Integration Approach:**
How this feature fits with existing commands/agents/modes
**Implementation Ideas:**
Technical approach or reference implementations
**Priority Level:**
Low/Medium/High based on development impact
```
**Enhancement Process:**
1. Open GitHub issue with `enhancement` label
2. Community discussion and feedback
3. Design review by maintainers
4. Implementation planning and assignment
5. Code development with tests
6. Documentation updates
7. Release integration
**Current Focus Areas:**
- Documentation improvements and examples
- MCP server configurations and troubleshooting
- Command workflow optimization
- Agent coordination patterns
- Quality assurance automation
### 📝 Documentation
**High-Impact Documentation Needs:**
**User Experience Improvements:**
- Real-world workflow examples and case studies
- Video tutorials for complex command sequences
- Interactive command discovery and learning paths
- Troubleshooting guides for common configuration issues
**Technical Documentation:**
- MCP server setup and configuration guides
- Agent coordination patterns and best practices
- Custom behavioral mode development
- Framework extension and customization
**Community Resources:**
- Contributing guides for different skill levels
- Code review standards and processes
- Testing procedures and quality gates
- Release notes and changelog maintenance
**Documentation Standards:**
- Clear, actionable instructions with examples
- Progressive complexity (beginner → advanced)
- Cross-references between related concepts
- Regular testing of documented procedures
**Easy Contributions:**
- Fix typos and grammar issues
- Add missing code examples
- Improve existing explanations
- Create new cookbook recipes
- Update outdated screenshots or commands
**Documentation Structure:**
```
Getting-Started/ # Installation and first steps
User-Guide/ # Feature usage and workflows
Developer-Guide/ # Technical implementation
Reference/ # Best practices and troubleshooting
```
**Contribution Process:**
1. Fork repository and create feature branch
2. Make documentation changes with examples
3. Test all commands and procedures
4. Submit pull request with clear description
5. Address review feedback promptly
### 🔧 Code Contributions
**Current Development Priorities:**
**Framework Core:**
- Command parser improvements and error handling
- Agent routing optimization and coordination
- Session management and persistence enhancements
- Quality gate implementation and validation
**MCP Integration:**
- New server configurations and troubleshooting
- Protocol optimization and error recovery
- Cross-server coordination patterns
- Performance monitoring and optimization
**Agent Development:**
- Specialized domain agents (mobile, ML, DevSecOps)
- Agent collaboration patterns and workflows
- Context-aware activation improvements
- Multi-agent task decomposition
**User Experience:**
- Command discoverability and help systems
- Progressive complexity and learning paths
- Error messages and user guidance
- Workflow automation and shortcuts
**Code Contribution Guidelines:**
- Follow existing code style and patterns
- Include comprehensive tests for new features
- Document all public APIs and interfaces
- Ensure backward compatibility where possible
- Add examples and usage documentation
**Technical Standards:**
- Python 3.8+ compatibility
- Cross-platform support (Linux, macOS, Windows)
- Comprehensive error handling and logging
- Performance optimization for large projects
- Security best practices for external integrations
**Development Workflow:**
1. Review [Technical Architecture](docs/Developer-Guide/technical-architecture.md)
2. Study [Contributing Code Guide](docs/Developer-Guide/contributing-code.md)
3. Set up development environment
4. Create feature branch from `master`
5. Implement changes with tests
6. Update documentation
7. Submit pull request with detailed description
**Code Review Focus:**
- Functionality correctness and edge cases
- Integration with existing framework components
- Performance impact and resource usage
- Documentation completeness and clarity
- Test coverage and quality
For detailed development guidelines, see [Contributing Code Guide](docs/Developer-Guide/contributing-code.md).
## 🤝 Community Guidelines
### Be Respectful
All community interactions should embody professional software development standards:
**Professional Communication:**
- Use clear, technical language appropriate for software development
- Provide specific, actionable feedback with examples
- Focus discussions on technical merit and project goals
- Respect different experience levels and learning approaches
**Constructive Collaboration:**
- Assume positive intent in all interactions
- Ask clarifying questions before making assumptions
- Provide helpful context and reasoning for decisions
- Acknowledge good contributions and helpful community members
**Technical Focus:**
- Keep discussions centered on software development and framework improvement
- Base decisions on technical merit, user value, and project alignment
- Use evidence and examples to support arguments
- Maintain focus on practical utility over theoretical perfection
**Inclusive Environment:**
- Welcome contributors of all skill levels and backgrounds
- Provide mentorship and guidance for new contributors
- Create learning opportunities through code review and discussion
- Celebrate diverse perspectives and solution approaches
### Stay Focused
**Project Focus:**
SuperClaude Framework enhances Claude Code for systematic software development workflows. Contributions should align with this core mission.
**In Scope:**
- Software development workflow automation
- Domain-specific agent development (security, performance, architecture)
- MCP server integrations for enhanced capabilities
- Quality assurance and validation systems
- Session management and project persistence
- Educational content for software development practices
**Out of Scope:**
- General-purpose AI applications unrelated to software development
- Features that significantly increase complexity without clear developer value
- Platform-specific implementations that don't support cross-platform usage
- Commercial or proprietary integrations without open alternatives
**Decision Framework:**
1. **Developer Value**: Does this help software developers build better systems?
2. **Framework Integration**: Does this work well with existing commands/agents/modes?
3. **Maintenance Burden**: Can this be maintained with available resources?
4. **Educational Merit**: Does this teach good software development practices?
**Scope Boundaries:**
- Focus on software development, not general productivity
- Enhance existing workflows rather than creating entirely new paradigms
- Maintain simplicity while adding powerful capabilities
- Support professional development practices and quality standards
### Quality First
**Code Quality Standards:**
**Technical Excellence:**
- All code must pass existing test suites
- New features require comprehensive test coverage (>90%)
- Follow established coding patterns and architectural principles
- Include proper error handling and edge case management
- Optimize for performance and resource efficiency
**Documentation Requirements:**
- All public APIs must have clear documentation with examples
- User-facing features need usage guides and cookbook recipes
- Code changes require updated relevant documentation
- Breaking changes must include migration guides
**User Experience Standards:**
- Commands should be discoverable and self-explanatory
- Error messages must be actionable and helpful
- Features should follow progressive complexity principles
- Maintain consistency with existing interface patterns
**Quality Gates:**
- Automated testing for all core functionality
- Manual testing for user workflows and integration scenarios
- Code review by at least one maintainer
- Documentation review for clarity and completeness
- Performance impact assessment for changes
**Professional Standards:**
- Code should be production-ready, not prototype quality
- Follow security best practices for external integrations
- Ensure cross-platform compatibility and proper dependency management
- Maintain backward compatibility or provide clear migration paths
## 💬 Getting Help
### Channels
**GitHub Issues** (Primary Support)
- Bug reports and technical issues
- Feature requests and enhancement proposals
- Documentation improvements and clarifications
- General troubleshooting with community help
**GitHub Discussions**
- General questions about usage and best practices
- Sharing workflows and success stories
- Community-driven tips and patterns
- Design discussions for major features
**Documentation Resources**
- [Troubleshooting Guide](docs/Reference/troubleshooting.md) - Common issues and solutions
- [Examples Cookbook](docs/Reference/examples-cookbook.md) - Practical usage patterns
- [Quick Start Practices](docs/Reference/quick-start-practices.md) - Optimization strategies
- [Technical Architecture](docs/Developer-Guide/technical-architecture.md) - Framework design
**Development Support**
- [Contributing Code Guide](docs/Developer-Guide/contributing-code.md) - Development setup
- [Testing & Debugging](docs/Developer-Guide/testing-debugging.md) - Quality procedures
- Code review process through pull requests
- Maintainer guidance on complex contributions
**Response Expectations:**
- Bug reports: 1-3 business days
- Feature requests: Review within 1 week
- Pull requests: Initial review within 3-5 days
- Documentation issues: Quick turnaround when straightforward
**Self-Help First:**
Before seeking support, please:
1. Check existing documentation and troubleshooting guides
2. Search GitHub issues for similar problems
3. Verify you're using the latest SuperClaude version
4. Test with minimal reproduction case
### Common Questions
**Development Environment Issues:**
**Q: "SuperClaude install fails with permission errors"**
A: Use `pip install --user SuperClaude` or create virtual environment. See [Installation Guide](docs/Getting-Started/installation.md) for details.
**Q: "Commands not recognized after installation"**
A: Restart Claude Code session. Verify installation with `SuperClaude install --list-components`. Check ~/.claude directory exists.
**Q: "MCP servers not connecting"**
A: Check Node.js installation for MCP servers. Verify ~/.claude/.claude.json configuration. Try `SuperClaude install --components mcp --force`.
**Code Development:**
**Q: "How do I add a new agent?"**
A: Follow agent patterns in setup/components/agents.py. Include trigger keywords, capabilities description, and integration tests.
**Q: "Testing framework setup?"**
A: See [Testing & Debugging Guide](docs/Developer-Guide/testing-debugging.md). Use pytest for Python tests, include component validation.
**Q: "Documentation structure?"**
A: Follow existing patterns: Getting-Started → User-Guide → Developer-Guide → Reference. Include examples and progressive complexity.
**Feature Development:**
**Q: "How do I propose a new command?"**
A: Open GitHub issue with use case, integration approach, and technical design. Reference similar existing commands.
**Q: "MCP server integration process?"**
A: Study existing MCP configurations in setup/components/mcp.py. Include server documentation, configuration examples, and troubleshooting.
**Q: "Performance optimization guidelines?"**
A: Profile before optimizing. Focus on common workflows. Maintain cross-platform compatibility. Document performance characteristics.
## 📄 License
**MIT License Agreement:**
By contributing to SuperClaude Framework, you agree that your contributions will be licensed under the same MIT License that covers the project. This ensures the framework remains open and accessible for educational and commercial use.
**Contribution Terms:**
- All contributions become part of the SuperClaude Framework under MIT License
- Contributors retain copyright to their original work
- No contributor license agreement (CLA) required for simple contributions
- Complex contributions may require explicit license confirmation
**Third-Party Content:**
- Do not include copyrighted code without proper attribution and compatible licensing
- External libraries must use MIT-compatible licenses (Apache 2.0, BSD, etc.)
- Document any third-party dependencies in requirements and documentation
- Respect intellectual property and attribution requirements
**Original Work:**
- Ensure all contributed code is your original work or properly attributed
- Reference external sources, algorithms, or patterns appropriately
- Include proper attribution for adapted or derived code
- Document any patent or licensing considerations
**Commercial Usage:**
The MIT License explicitly allows commercial use of SuperClaude Framework, including contributions. This supports the project's goal of enabling professional software development workflows.
## 🙏 Acknowledgments
**Project Contributors:**
SuperClaude Framework benefits from community contributions across documentation, code development, testing, and user experience improvements.
**Recognition:**
- [GitHub Contributors Graph](https://github.com/SuperClaude-Org/SuperClaude_Framework/graphs/contributors) - Complete contributor list
- Release notes acknowledge significant contributions
- Documentation contributors credited in relevant guides
- Community discussions highlight helpful patterns and solutions
**Community Impact:**
- Enhanced developer productivity through systematic workflows
- Educational value for software development practices
- Open-source contribution to AI-assisted development tools
- Cross-platform compatibility and accessibility
**Contribution Types:**
- **Code Development**: Framework features, agents, MCP integrations
- **Documentation**: Guides, examples, troubleshooting resources
- **Testing**: Quality assurance, edge case discovery, platform validation
- **Community**: Support, pattern sharing, feedback, and usage examples
**Special Thanks:**
- Early adopters providing feedback and real-world usage patterns
- Documentation contributors improving clarity and completeness
- Testers identifying platform-specific issues and edge cases
- Community members sharing workflows and best practices
**Growth:**
The SuperClaude Framework community continues growing through shared commitment to systematic software development and AI-assisted workflows. Every contribution, from typo fixes to major features, strengthens the framework for all users.
**Join Us:**
Whether you're fixing documentation, adding features, or sharing usage patterns, your contributions help build better software development tools for the entire community.
================================================
FILE: DELETION_RATIONALE.md
================================================
# Deletion Rationale (Evidence-Based)
**PR Target Branch**: `next`
**Base Branch**: `master`
**Date**: 2025-10-24
---
## 📊 Deletion Summary
| Category | Deleted Files | Deleted Lines | Reason Category |
|---------|--------------|---------------|-----------------|
| setup/ directory | 40 | 12,289 | Architecture renovation |
| superclaude/ (old structure) | 86 | ~8,000 | PEP 517 migration |
| TypeScript implementation | 14 | 2,633 | Preserved in branch |
| Plugin files | 9 | 494 | Repository separation |
| bin/ + scripts/ | 8 | ~800 | CLI modernization |
| **Total** | **~157** | **~22,507** | - |
---
## 1. setup/ Directory Deletion (12,289 lines)
### What Was Deleted
```
setup/
├── cli/ # Old CLI commands (backup, install, uninstall, update)
├── components/ # Installers for agents, modes, commands
├── core/ # Installer, registry, validator
├── services/ # claude_md, config, files, settings
└── utils/ # logger, paths, security, symbols, ui, updater
```
### Deletion Rationale (Evidence)
**Evidence 1: Commit Message**
```
commit eb37591
refactor: remove legacy setup/ system and dependent tests
Remove old installation system (setup/) that caused heavy token consumption
```
**Evidence 2: PHASE_2_COMPLETE.md**
```markdown
New architecture (src/superclaude/) is self-contained and doesn't need setup/.
```
**Evidence 3: Architecture Migration Rationale**
- Old system: Copied files to `~/.claude/superclaude/` → **Polluted user environment**
- New system: Installed to `site-packages/` → **Standard Python package**
**Evidence 4: Token Efficiency**
- Old setup/: Complex installation logic, backup functionality, security checks
- New system: Complete with `uv pip install -e ".[dev]"`
**Logical Conclusion**:
- ✅ Migrated to PEP 517 compliant build system (hatchling)
- ✅ Uses standard Python package management (UV)
- ✅ Zero `~/.claude/` pollution
- ✅ Significantly reduced maintenance burden
---
## 2. superclaude/ Directory Deletion (Old Structure)
### What Was Deleted
```
superclaude/
├── agents/ # 20 agent definitions
├── commands/ # 27 slash commands
├── modes/ # 7 behavior modes
├── framework/ # PRINCIPLES, RULES, FLAGS
├── business/ # Business panel
└── cli/ # Old CLI tools
```
### Deletion Rationale (Evidence)
**Evidence 1: Python Package Directory Layout Research**
```markdown
File: docs/research/python_src_layout_research_20251021.md
## Recommendation
Use src/ layout for SuperClaude:
- Clear separation between package code and tests
- Prevents accidental imports from development directory
- Modern Python best practice
```
**Evidence 2: Migration Completion Proof**
```bash
# Old structure
superclaude/pm_agent/confidence.py
# New structure (PEP 517 compliant)
src/superclaude/pm_agent/confidence.py
```
**Evidence 3: pytest plugin auto-discovery**
```bash
$ uv run python -m pytest --trace-config 2>&1 | grep "registered third-party plugins:"
registered third-party plugins:
superclaude-0.4.0 at /Users/kazuki/github/superclaude/src/superclaude/pytest_plugin.py
```
**Logical Conclusion**:
- ✅ src/ layout is official Python recommendation
- ✅ Clear separation between package and tests
- ✅ Prevents accidental imports from development directory
- ✅ Entry point auto-discovery verified working
---
## 3. 27 Slash Commands Deletion
### What Was Deleted
```
~/.claude/commands/sc/ (27 commands):
- analyze, brainstorm, build, business-panel, cleanup
- design, document, estimate, explain, git, help
- implement, improve, index, load, pm, reflect
- research, save, select-tool, spawn, spec-panel
- task, test, troubleshoot, workflow
```
### Deletion Rationale (Evidence)
**Evidence 1: Commit Message**
```
commit 06e7c00
feat: migrate research and index-repo to plugin, delete all slash commands
## Architecture Change
Strategy: Minimal start with PM Agent orchestration
- PM Agent = orchestrator (command coordinator)
- Task tool (general-purpose, Explore) = execution
- Plugin commands = specialized tasks when needed
- Avoid reinventing the wheel (use official tools first)
## Benefits
✅ Minimal footprint (3 commands vs 27)
✅ Plugin-based distribution
✅ Version control
✅ Easy to extend when needed
```
**Evidence 2: Claude Code Official Tools Priority Policy**
- Task tool: General-purpose task execution
- Explore agent: Codebase exploration
- These are **Claude Code built-in tools** - no need to reimplement
**Evidence 3: PM Agent Orchestration Strategy**
```markdown
File: commands/agent.md (SuperClaude_Plugin)
## Task Protocol
1. Clarify scope
2. Plan investigation
- @confidence-check skill (pre-implementation score ≥0.90 required)
- @deep-research agent (web/MCP research)
- @repo-index agent (repository structure + file shortlist)
- @self-review agent (post-implementation validation)
3. Iterate until confident
4. Implementation wave
5. Self-review and reflexion
```
**Evidence 4: Performance Data**
- 27 commands → 3 commands (pm, research, index-repo)
- Footprint reduction: **89% reduction**
- Can be extended as needed (plugin architecture)
**Logical Conclusion**:
- ✅ Eliminated overlap with Claude Code built-in tools
- ✅ PM Agent functions as orchestrator
- ✅ Started with minimal essential command set
- ✅ Designed for extensibility via plugins
---
## 4. TypeScript Implementation Deletion (2,633 lines)
### What Was Deleted
```
pm/
├── index.ts
├── confidence.ts
├── self-check.ts
├── reflexion.ts
└── __tests__/
research/
└── index.ts
index/
└── index.ts
```
### Deletion Rationale (Evidence)
**Evidence 1: Commit Message**
```
commit f511e04
chore: remove TypeScript implementation (saved in typescript-impl branch)
- TypeScript implementation preserved in typescript-impl branch for future reference
```
**Evidence 2: Branch Preservation Confirmation**
```bash
$ git branch --all | grep typescript-impl
typescript-impl
```
**Evidence 3: Avoiding Dual Implementation**
- TypeScript version: Hot reload plugin implementation (experimental)
- Python version: Production use (pytest plugin)
**Evidence 4: Markdown-based Command Superiority**
```markdown
File: commands/agent.md
# SC Agent Activation
🚀 **SC Agent online** — this plugin launches `/sc:agent` automatically at session start.
```
- Markdown is readable
- Natively supported by Claude Code
- TypeScript implementation was over-engineering
**Logical Conclusion**:
- ✅ TypeScript implementation saved in `typescript-impl` branch
- ✅ Maintained for future reference
- ✅ Current Markdown-based + Python implementation is sufficient
- ✅ Prioritized simplicity
---
## 5. Plugin Files Deletion (494 lines)
### What Was Deleted
```
.claude-plugin/
├── plugin.json
└── marketplace.json
agents/
├── deep-research.md
├── repo-index.md
└── self-review.md
commands/
├── pm.md
├── research.md
└── index-repo.md
hooks/
└── hooks.json
```
### Deletion Rationale (Evidence)
**Evidence 1: Commit Message**
```
commit 87c80d0
refactor: move plugin files to SuperClaude_Plugin repository
Plugin files now maintained in SuperClaude_Plugin repository.
This repository focuses on Python package implementation.
```
**Evidence 2: Repository Separation Rationale**
**SuperClaude_Framework (this repository)**:
- Python package implementation
- pytest plugin
- CLI tools (`superclaude` command)
- Documentation
**SuperClaude_Plugin (separate repository)**:
- Claude Code plugin
- Slash command definitions
- Agent definitions
- Hooks configuration
**Evidence 3: Clear Responsibility Separation**
```
SuperClaude_Framework:
Purpose: Distributed as Python library
Install: `uv pip install superclaude`
Target: pytest + CLI users
SuperClaude_Plugin:
Purpose: Distributed as Claude Code plugin
Install: `/plugin install sc@SuperClaude-Org`
Target: Claude Code users
```
**Logical Conclusion**:
- ✅ Separation of concerns (Python package vs Claude Code plugin)
- ✅ Independent version control
- ✅ Optimized distribution methods
- ✅ Distributed maintenance burden
---
## 6. bin/ + scripts/ Deletion (~800 lines)
### What Was Deleted
```
bin/
├── cli.js
├── check_env.js
├── check_update.js
├── install.js
└── update.js
scripts/
├── build_and_upload.py
├── validate_pypi_ready.py
└── verify_research_integration.sh
```
### Deletion Rationale (Evidence)
**Evidence 1: CLI Modernization Commit**
```
commit b23c9ce
feat: migrate CLI to typer + rich for modern UX
```
**Evidence 2: Old CLI vs New CLI**
**Old CLI (bin/cli.js)**:
- Node.js implementation
- Complex dependency checking
- Auto-update functionality
**New CLI (src/superclaude/cli/main.py)**:
```python
# Modern Python CLI with typer + rich
@app.command()
def doctor(verbose: bool = False):
"""Run health checks"""
# Simple, readable, maintainable
```
**Evidence 3: Obsolete Scripts**
- `build_and_upload.py` → Replaced by `uv build` + `uv publish`
- `validate_pypi_ready.py` → Replaced by `uv build --check`
- `verify_research_integration.sh` → Replaced by `uv run pytest`
**Logical Conclusion**:
- ✅ Eliminated Node.js dependency
- ✅ Modern Python CLI (typer + rich)
- ✅ Leveraged UV standard commands
- ✅ Simpler and more maintainable code
---
## 📈 Overall Impact
### Before (master)
- **Total lines**: ~45,000 lines
- **Directories**: setup/, superclaude/, bin/, scripts/, .claude-plugin/
- **Installation**: Complex `setup/` system
- **Distribution**: npm + PyPI
- **Dependencies**: Node.js + Python
### After (next)
- **Total lines**: ~22,500 lines (**50% reduction**)
- **Directories**: src/superclaude/, docs/, tests/
- **Installation**: `uv pip install -e ".[dev]"`
- **Distribution**: PyPI (plugin in separate repo)
- **Dependencies**: Python only
### Reduction Effects
- ✅ Code size: 50% reduction
- ✅ Dependencies: Node.js removed
- ✅ Maintenance: Significantly reduced with setup/ removal
- ✅ User environment pollution: Zero
- ✅ Installation time: Seconds
---
## ✅ Conclusion
All deletions were performed based on the following principles:
1. **Evidence-Based**: Backed by documentation, test results, commit history
2. **Logical**: Compliant with architecture principles, Python standards, Claude Code official recommendations
3. **Preserved**: TypeScript saved in branch, plugin moved to separate repository
4. **Verified**: All 97 tests passing, installation verified working
**Review Focus**:
- [ ] Architecture migration validity
- [ ] Sufficiency of deletion rationale
- [ ] Clarity of alternative solutions
- [ ] Test coverage maintenance
- [ ] Documentation consistency
================================================
FILE: KNOWLEDGE.md
================================================
# KNOWLEDGE.md
**Accumulated Insights, Best Practices, and Troubleshooting for SuperClaude Framework**
> This document captures lessons learned, common pitfalls, and solutions discovered during development.
> Consult this when encountering issues or learning project patterns.
**Last Updated**: 2025-11-12
---
## 🧠 **Core Insights**
### **PM Agent ROI: 25-250x Token Savings**
**Finding**: Pre-execution confidence checking has exceptional ROI.
**Evidence**:
- Spending 100-200 tokens on confidence check saves 5,000-50,000 tokens on wrong-direction work
- Real example: Checking for duplicate implementations before coding (2min research) vs implementing duplicate feature (2hr work)
**When it works best**:
- Unclear requirements → Ask questions first
- New codebase → Search for existing patterns
- Complex features → Verify architecture compliance
- Bug fixes → Identify root cause before coding
**When to skip**:
- Trivial changes (typo fixes)
- Well-understood tasks with clear path
- Emergency hotfixes (but document learnings after)
---
### **Hallucination Detection: 94% Accuracy**
**Finding**: The Four Questions catch most AI hallucinations.
**The Four Questions**:
1. Are all tests passing? → REQUIRE actual output
2. Are all requirements met? → LIST each requirement
3. No assumptions without verification? → SHOW documentation
4. Is there evidence? → PROVIDE test results, code changes, validation
**Red flags that indicate hallucination**:
- "Tests pass" (without showing output) 🚩
- "Everything works" (without evidence) 🚩
- "Implementation complete" (with failing tests) 🚩
- Skipping error messages 🚩
- Ignoring warnings 🚩
- "Probably works" language 🚩
**Real example**:
```
❌ BAD: "The API integration is complete and working correctly."
✅ GOOD: "The API integration is complete. Test output:
✅ test_api_connection: PASSED
✅ test_api_authentication: PASSED
✅ test_api_data_fetch: PASSED
All 3 tests passed in 1.2s"
```
---
### **Parallel Execution: 3.5x Speedup**
**Finding**: Wave → Checkpoint → Wave pattern dramatically improves performance.
**Pattern**:
```python
# Wave 1: Independent reads (parallel)
files = [Read(f1), Read(f2), Read(f3)]
# Checkpoint: Analyze together (sequential)
analysis = analyze_files(files)
# Wave 2: Independent edits (parallel)
edits = [Edit(f1), Edit(f2), Edit(f3)]
```
**When to use**:
- ✅ Reading multiple independent files
- ✅ Editing multiple unrelated files
- ✅ Running multiple independent searches
- ✅ Parallel test execution
**When NOT to use**:
- ❌ Operations with dependencies (file2 needs data from file1)
- ❌ Sequential analysis (building context step-by-step)
- ❌ Operations that modify shared state
**Performance data**:
- Sequential: 10 file reads = 10 API calls = ~30 seconds
- Parallel: 10 file reads = 1 API call = ~3 seconds
- Speedup: 3.5x average, up to 10x for large batches
---
## 🛠️ **Common Pitfalls and Solutions**
### **Pitfall 1: Implementing Before Checking for Duplicates**
**Problem**: Spent hours implementing feature that already exists in codebase.
**Solution**: ALWAYS use Glob/Grep before implementing:
```bash
# Search for similar functions
uv run python -c "from pathlib import Path; print([f for f in Path('src').rglob('*.py') if 'feature_name' in f.read_text()])"
# Or use grep
grep -r "def feature_name" src/
```
**Prevention**: Run confidence check, ensure duplicate_check_complete=True
---
### **Pitfall 2: Assuming Architecture Without Verification**
**Problem**: Implemented custom API when project uses Supabase.
**Solution**: READ CLAUDE.md and PLANNING.md before implementing:
```python
# Check project tech stack
with open('CLAUDE.md') as f:
claude_md = f.read()
if 'Supabase' in claude_md:
# Use Supabase APIs, not custom implementation
```
**Prevention**: Run confidence check, ensure architecture_check_complete=True
---
### **Pitfall 3: Skipping Test Output**
**Problem**: Claimed tests passed but they were actually failing.
**Solution**: ALWAYS show actual test output:
```bash
# Run tests and capture output
uv run pytest -v > test_output.txt
# Show in validation
echo "Test Results:"
cat test_output.txt
```
**Prevention**: Use SelfCheckProtocol, require evidence
---
### **Pitfall 4: Version Inconsistency**
**Problem**: VERSION file says 4.1.9, but package.json says 4.1.5, pyproject.toml says 0.4.0.
**Solution**: Understand versioning strategy:
- **Framework version** (VERSION file): User-facing version (4.1.9)
- **Python package** (pyproject.toml): Library semantic version (0.4.0)
- **NPM package** (package.json): Should match framework version (4.1.9)
**When updating versions**:
1. Update VERSION file first
2. Update package.json to match
3. Update README badges
4. Consider if pyproject.toml needs bump (breaking changes?)
5. Update CHANGELOG.md
**Prevention**: Create release checklist
---
### **Pitfall 5: UV Not Installed**
**Problem**: Makefile requires `uv` but users don't have it.
**Solution**: Install UV:
```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# With pip
pip install uv
```
**Alternative**: Provide fallback commands:
```bash
# With UV (preferred)
uv run pytest
# Without UV (fallback)
python -m pytest
```
**Prevention**: Document UV requirement in README
---
## 📚 **Best Practices**
### **Testing Best Practices**
**1. Use pytest markers for organization**:
```python
@pytest.mark.unit
def test_individual_function():
pass
@pytest.mark.integration
def test_component_interaction():
pass
@pytest.mark.confidence_check
def test_with_pre_check(confidence_checker):
pass
```
**2. Use fixtures for shared setup**:
```python
# conftest.py
@pytest.fixture
def sample_context():
return {...}
# test_file.py
def test_feature(sample_context):
# Use sample_context
```
**3. Test both happy path and edge cases**:
```python
def test_feature_success():
# Normal operation
def test_feature_with_empty_input():
# Edge case
def test_feature_with_invalid_data():
# Error handling
```
---
### **Git Workflow Best Practices**
**1. Conventional commits**:
```bash
git commit -m "feat: add confidence checking to PM Agent"
git commit -m "fix: resolve version inconsistency"
git commit -m "docs: update CLAUDE.md with plugin warnings"
git commit -m "test: add unit tests for reflexion pattern"
```
**2. Small, focused commits**:
- Each commit should do ONE thing
- Commit message should explain WHY, not WHAT
- Code changes should be reviewable in <500 lines
**3. Branch naming**:
```bash
feature/add-confidence-check
fix/version-inconsistency
docs/update-readme
refactor/simplify-cli
test/add-unit-tests
```
---
### **Documentation Best Practices**
**1. Code documentation**:
```python
def assess(self, context: Dict[str, Any]) -> float:
"""
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%)
Args:
context: Context dict with task details
Returns:
float: Confidence score (0.0 = no confidence, 1.0 = absolute certainty)
Example:
>>> checker = ConfidenceChecker()
>>> confidence = checker.assess(context)
>>> if confidence >= 0.9:
... proceed_with_implementation()
"""
```
**2. README structure**:
- Start with clear value proposition
- Quick installation instructions
- Usage examples
- Link to detailed docs
- Contribution guidelines
- License
**3. Keep docs synchronized with code**:
- Update docs in same PR as code changes
- Review docs during code review
- Use automated doc generation where possible
---
## 🔧 **Troubleshooting Guide**
### **Issue: Tests Not Found**
**Symptoms**:
```
$ uv run pytest
ERROR: file or directory not found: tests/
```
**Cause**: tests/ directory doesn't exist
**Solution**:
```bash
# Create tests structure
mkdir -p tests/unit tests/integration
# Add __init__.py files
touch tests/__init__.py
touch tests/unit/__init__.py
touch tests/integration/__init__.py
# Add conftest.py
touch tests/conftest.py
```
---
### **Issue: Plugin Not Loaded**
**Symptoms**:
```
$ uv run pytest --trace-config
# superclaude not listed in plugins
```
**Cause**: Package not installed or entry point not configured
**Solution**:
```bash
# Reinstall in editable mode
uv pip install -e ".[dev]"
# Verify entry point in pyproject.toml
# Should have:
# [project.entry-points.pytest11]
# superclaude = "superclaude.pytest_plugin"
# Test plugin loaded
uv run pytest --trace-config 2>&1 | grep superclaude
```
---
### **Issue: ImportError in Tests**
**Symptoms**:
```python
ImportError: No module named 'superclaude'
```
**Cause**: Package not installed in test environment
**Solution**:
```bash
# Install package in editable mode
uv pip install -e .
# Or use uv run (creates venv automatically)
uv run pytest
```
---
### **Issue: Fixtures Not Available**
**Symptoms**:
```python
fixture 'confidence_checker' not found
```
**Cause**: pytest plugin not loaded or fixture not defined
**Solution**:
```bash
# Check plugin loaded
uv run pytest --fixtures | grep confidence_checker
# Verify pytest_plugin.py has fixture
# Should have:
# @pytest.fixture
# def confidence_checker():
# return ConfidenceChecker()
# Reinstall package
uv pip install -e .
```
---
### **Issue: .gitignore Not Working**
**Symptoms**: Files listed in .gitignore still tracked by git
**Cause**: Files were tracked before adding to .gitignore
**Solution**:
```bash
# Remove from git but keep in filesystem
git rm --cached <file>
# OR remove entire directory
git rm -r --cached <directory>
# Commit the change
git commit -m "fix: remove tracked files from gitignore"
```
---
## 💡 **Advanced Techniques**
### **Technique 1: Dynamic Fixture Configuration**
```python
@pytest.fixture
def token_budget(request):
"""Fixture that adapts based on test markers"""
marker = request.node.get_closest_marker("complexity")
complexity = marker.args[0] if marker else "medium"
return TokenBudgetManager(complexity=complexity)
# Usage
@pytest.mark.complexity("simple")
def test_simple_feature(token_budget):
assert token_budget.limit == 200
```
---
### **Technique 2: Confidence-Driven Test Execution**
```python
def pytest_runtest_setup(item):
"""Skip tests if confidence is too low"""
marker = item.get_closest_marker("confidence_check")
if marker:
checker = ConfidenceChecker()
context = build_context(item)
confidence = checker.assess(context)
if confidence < 0.7:
pytest.skip(f"Confidence too low: {confidence:.0%}")
```
---
### **Technique 3: Reflexion-Powered Error Learning**
```python
def pytest_runtest_makereport(item, call):
"""Record failed tests for future learning"""
if call.when == "call" and call.excinfo is not None:
reflexion = ReflexionPattern()
error_info = {
"test_name": item.name,
"error_type": type(call.excinfo.value).__name__,
"error_message": str(call.excinfo.value),
}
reflexion.record_error(error_info)
```
---
## 📊 **Performance Insights**
### **Token Usage Patterns**
Based on real usage data:
| Task Type | Typical Tokens | With PM Agent | Savings |
|-----------|---------------|---------------|---------|
| Typo fix | 200-500 | 200-300 | 40% |
| Bug fix | 2,000-5,000 | 1,000-2,000 | 50% |
| Feature | 10,000-50,000 | 5,000-15,000 | 60% |
| Wrong direction | 50,000+ | 100-200 (prevented) | 99%+ |
**Key insight**: Prevention (confidence check) saves more tokens than optimization
---
### **Execution Time Patterns**
| Operation | Sequential | Parallel | Speedup |
|-----------|-----------|----------|---------|
| 5 file reads | 15s | 3s | 5x |
| 10 file reads | 30s | 3s | 10x |
| 20 file edits | 60s | 15s | 4x |
| Mixed ops | 45s | 12s | 3.75x |
**Key insight**: Parallel execution has diminishing returns after ~10 operations per wave
---
## 🎓 **Lessons Learned**
### **Lesson 1: Documentation Drift is Real**
**What happened**: README described v2.0 plugin system that didn't exist in v4.1.9
**Impact**: Users spent hours trying to install non-existent features
**Solution**:
- Add warnings about planned vs implemented features
- Review docs during every release
- Link to tracking issues for planned features
**Prevention**: Documentation review checklist in release process
---
### **Lesson 2: Version Management is Hard**
**What happened**: Three different version numbers across files
**Impact**: Confusion about which version is installed
**Solution**:
- Define version sources of truth
- Document versioning strategy
- Automate version updates in release script
**Prevention**: Single-source-of-truth for versions (maybe use bumpversion)
---
### **Lesson 3: Tests Are Non-Negotiable**
**What happened**: Framework provided testing tools but had no tests itself
**Impact**: No confidence in code quality, regression bugs
**Solution**:
- Create comprehensive test suite
- Require tests for all new code
- Add CI/CD to run tests automatically
**Prevention**: Make tests a requirement in PR template
---
## 🔮 **Future Explorations**
Ideas worth investigating:
1. **Automated confidence checking** - AI analyzes context and suggests improvements
2. **Visual reflexion patterns** - Graph view of error patterns over time
3. **Predictive token budgeting** - ML model predicts token usage based on task
4. **Collaborative learning** - Share reflexion patterns across projects (opt-in)
5. **Real-time hallucination detection** - Streaming analysis during generation
---
## 📞 **Getting Help**
**When stuck**:
1. Check this KNOWLEDGE.md for similar issues
2. Read PLANNING.md for architecture context
3. Check TASK.md for known issues
4. Search GitHub issues for solutions
5. Ask in GitHub discussions
**When sharing knowledge**:
1. Document solution in this file
2. Update relevant section
3. Add to troubleshooting guide if applicable
4. Consider adding to FAQ
---
*This document grows with the project. Everyone who encounters a problem and finds a solution should document it here.*
**Contributors**: SuperClaude development team and community
**Maintained by**: Project maintainers
**Review frequency**: Quarterly or after major insights
================================================
FILE: LICENSE
================================================
MIT License
Copyright (c) 2024 SuperClaude Framework Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
================================================
FILE: MANIFEST.in
================================================
include VERSION
include README.md
include LICENSE
include CHANGELOG.md
include CONTRIBUTING.md
include SECURITY.md
include pyproject.toml
recursive-include docs *.md *.json *.py
recursive-include tests *.py
recursive-include src/superclaude *.py *.md *.ts *.json *.sh
recursive-include src/superclaude/commands *.md
recursive-include src/superclaude/agents *.md
recursive-include src/superclaude/modes *.md
recursive-include src/superclaude/mcp *.md *.json
recursive-include src/superclaude/core *.md
recursive-include src/superclaude/examples *.md
recursive-include src/superclaude/hooks *.json
recursive-include src/superclaude/scripts *.py *.sh
recursive-include src/superclaude/skills *.md *.ts *.json
recursive-include plugins/superclaude *.py *.md *.ts *.json *.sh
recursive-include plugins/superclaude/commands *.md
recursive-include plugins/superclaude/agents *.md
recursive-include plugins/superclaude/modes *.md
recursive-include plugins/superclaude/mcp *.py *.md *.json
recursive-include plugins/superclaude/mcp/configs *.json
recursive-include plugins/superclaude/core *.md
recursive-include plugins/superclaude/examples *.md
recursive-include plugins/superclaude/hooks *.json
recursive-include plugins/superclaude/scripts *.py *.sh
recursive-include plugins/superclaude/skills *.py *.md *.ts *.json
global-exclude __pycache__
global-exclude *.py[co]
global-exclude .DS_Store
================================================
FILE: Makefile
================================================
.PHONY: install test test-plugin doctor verify clean lint format build-plugin sync-plugin-repo uninstall-legacy help
# Installation (local source, editable) - RECOMMENDED
install:
@echo "🔧 Installing SuperClaude Framework (development mode)..."
uv pip install -e ".[dev]"
@echo ""
@echo "✅ Installation complete!"
@echo " Run 'make verify' to check installation"
# Run tests
test:
@echo "Running tests..."
uv run pytest
# Test pytest plugin loading
test-plugin:
@echo "Testing pytest plugin auto-discovery..."
@uv run python -m pytest --trace-config 2>&1 | grep -A2 "registered third-party plugins:" | grep superclaude && echo "✅ Plugin loaded successfully" || echo "❌ Plugin not loaded"
# Run doctor command
doctor:
@echo "Running SuperClaude health check..."
@uv run superclaude doctor
# Verify Phase 1 installation
verify:
@echo "🔍 Phase 1 Installation Verification"
@echo "======================================"
@echo ""
@echo "1. Package location:"
@uv run python -c "import superclaude; print(f' {superclaude.__file__}')"
@echo ""
@echo "2. Package version:"
@uv run superclaude --version | sed 's/^/ /'
@echo ""
@echo "3. Pytest plugin:"
@uv run python -m pytest --trace-config 2>&1 | grep "registered third-party plugins:" -A2 | grep superclaude | sed 's/^/ /' && echo " ✅ Plugin loaded" || echo " ❌ Plugin not loaded"
@echo ""
@echo "4. Health check:"
@uv run superclaude doctor | grep "SuperClaude is healthy" > /dev/null && echo " ✅ All checks passed" || echo " ❌ Some checks failed"
@echo ""
@echo "======================================"
@echo "✅ Phase 1 verification complete"
# Linting
lint:
@echo "Running linter..."
uv run ruff check .
# Format code
format:
@echo "Formatting code..."
uv run ruff format .
# Clean build artifacts
clean:
@echo "Cleaning build artifacts..."
rm -rf build/ dist/ *.egg-info
find . -type d -name __pycache__ -exec rm -rf {} +
find . -type d -name .pytest_cache -exec rm -rf {} +
find . -type d -name .ruff_cache -exec rm -rf {} +
PLUGIN_DIST := dist/plugins/superclaude
PLUGIN_REPO ?= ../SuperClaude_Plugin
.PHONY: build-plugin
build-plugin: ## Build SuperClaude plugin artefacts into dist/
@echo "🛠️ Building SuperClaude plugin from unified sources..."
@uv run python scripts/build_superclaude_plugin.py
.PHONY: sync-plugin-repo
sync-plugin-repo: build-plugin ## Sync built plugin artefacts into ../SuperClaude_Plugin
@if [ ! -d "$(PLUGIN_REPO)" ]; then \
echo "❌ Target plugin repository not found at $(PLUGIN_REPO)"; \
echo " Set PLUGIN_REPO=/path/to/SuperClaude_Plugin when running make."; \
exit 1; \
fi
@echo "📦 Syncing artefacts to $(PLUGIN_REPO)..."
@rsync -a --delete $(PLUGIN_DIST)/agents/ $(PLUGIN_REPO)/agents/
@rsync -a --delete $(PLUGIN_DIST)/commands/ $(PLUGIN_REPO)/commands/
@rsync -a --delete $(PLUGIN_DIST)/hooks/ $(PLUGIN_REPO)/hooks/
@rsync -a --delete $(PLUGIN_DIST)/scripts/ $(PLUGIN_REPO)/scripts/
@rsync -a --delete $(PLUGIN_DIST)/skills/ $(PLUGIN_REPO)/skills/
@rsync -a --delete $(PLUGIN_DIST)/.claude-plugin/ $(PLUGIN_REPO)/.claude-plugin/
@echo "✅ Sync complete."
# Translate README to multiple languages using Neural CLI
translate:
@echo "🌐 Translating README using Neural CLI (Ollama + qwen2.5:3b)..."
@if [ ! -f ~/.local/bin/neural-cli ]; then \
echo "📦 Installing neural-cli..."; \
mkdir -p ~/.local/bin; \
ln -sf ~/github/neural/src-tauri/target/release/neural-cli ~/.local/bin/neural-cli; \
echo "✅ neural-cli installed to ~/.local/bin/"; \
fi
@echo ""
@echo "🇨🇳 Translating to Simplified Chinese..."
@~/.local/bin/neural-cli translate README.md --from English --to "Simplified Chinese" --output README-zh.md
@echo ""
@echo "🇯🇵 Translating to Japanese..."
@~/.local/bin/neural-cli translate README.md --from English --to Japanese --output README-ja.md
@echo ""
@echo "✅ Translation complete!"
@echo "📝 Files updated: README-zh.md, README-ja.md"
# Show help
help:
@echo "SuperClaude Framework - Available commands:"
@echo ""
@echo "🚀 Quick Start:"
@echo " make install - Install in development mode (RECOMMENDED)"
@echo " make verify - Verify installation is working"
@echo ""
@echo "🔧 Development:"
@echo " make test - Run test suite"
@echo " make test-plugin - Test pytest plugin auto-discovery"
@echo " make doctor - Run health check"
@echo " make lint - Run linter (ruff check)"
@echo " make format - Format code (ruff format)"
@echo " make clean - Clean build artifacts"
@echo ""
@echo "🔌 Plugin Packaging:"
@echo " make build-plugin - Build SuperClaude plugin artefacts into dist/"
@echo " make sync-plugin-repo - Sync artefacts into ../SuperClaude_Plugin"
@echo ""
@echo "📚 Documentation:"
@echo " make translate - Translate README to Chinese and Japanese"
@echo ""
@echo "🧹 Cleanup:"
@echo " make uninstall-legacy - Remove old SuperClaude files from ~/.claude"
@echo " make help - Show this help message"
# Remove legacy SuperClaude files from ~/.claude directory
uninstall-legacy:
@echo "🧹 Cleaning up legacy SuperClaude files..."
@bash scripts/uninstall_legacy.sh
@echo ""
================================================
FILE: PARALLEL_INDEXING_PLAN.md
================================================
# Parallel Repository Indexing Execution Plan
## Objective
Create comprehensive repository index for: /Users/kazuki/github/SuperClaude_Framework
## Execution Strategy
Execute the following 5 tasks IN PARALLEL using Task tool.
IMPORTANT: All 5 Task tool calls must be in a SINGLE message for parallel execution.
## Tasks to Execute (Parallel)
### Task 1: Analyze code structure
- Agent: Explore
- ID: code_structure
**Prompt**:
```
Analyze the code structure of this repository: /Users/kazuki/github/SuperClaude_Framework
Task: Find and analyze all source code directories (src/, lib/, superclaude/, setup/, apps/, packages/)
For each directory found:
1. List all Python/JavaScript/TypeScript files
2. Identify the purpose/responsibility
3. Note key files and entry points
4. Detect any organizational issues
Output format (JSON):
{
"directories": [
{
"path": "relative/path",
"purpose": "description",
"file_count": 10,
"key_files": ["file1.py", "file2.py"],
"issues": ["redundant nesting", "orphaned files"]
}
],
"total_files": 100
}
Use Glob and Grep tools to search efficiently.
Be thorough: "very thorough" level.
```
### Task 2: Analyze documentation
- Agent: Explore
- ID: documentation
**Prompt**:
```
Analyze the documentation of this repository: /Users/kazuki/github/SuperClaude_Framework
Task: Find and analyze all documentation (docs/, README*, *.md files)
For each documentation section:
1. List all markdown/rst files
2. Assess documentation coverage
3. Identify missing documentation
4. Detect redundant/duplicate docs
Output format (JSON):
{
"directories": [
{
"path": "docs/",
"purpose": "User/developer documentation",
"file_count": 50,
"coverage": "good|partial|poor",
"missing": ["API reference", "Architecture guide"],
"duplicates": ["README vs docs/README"]
}
],
"root_docs": ["README.md", "CLAUDE.md"],
"total_files": 75
}
Use Glob to find all .md files.
Check for duplicate content patterns.
```
### Task 3: Analyze configuration files
- Agent: Explore
- ID: configuration
**Prompt**:
```
Analyze the configuration files of this repository: /Users/kazuki/github/SuperClaude_Framework
Task: Find and analyze all configuration files (.toml, .yaml, .yml, .json, .ini, .cfg)
For each config file:
1. Identify purpose (build, deps, CI/CD, etc.)
2. Note importance level
3. Check for issues (deprecated, unused)
Output format (JSON):
{
"config_files": [
{
"path": "pyproject.toml",
"type": "python_project",
"importance": "critical",
"issues": []
}
],
"total_files": 15
}
Use Glob with appropriate patterns.
```
### Task 4: Analyze test structure
- Agent: Explore
- ID: tests
**Prompt**:
```
Analyze the test structure of this repository: /Users/kazuki/github/SuperClaude_Framework
Task: Find and analyze all tests (tests/, __tests__/, *.test.*, *.spec.*)
For each test directory/file:
1. Count test files
2. Identify test types (unit, integration, performance)
3. Assess coverage (if pytest/coverage data available)
Output format (JSON):
{
"test_directories": [
{
"path": "tests/",
"test_count": 20,
"types": ["unit", "integration", "benchmark"],
"coverage": "unknown"
}
],
"total_tests": 25
}
Use Glob to find test files.
```
### Task 5: Analyze scripts and utilities
- Agent: Explore
- ID: scripts
**Prompt**:
```
Analyze the scripts and utilities of this repository: /Users/kazuki/github/SuperClaude_Framework
Task: Find and analyze all scripts (scripts/, bin/, tools/, *.sh, *.bash)
For each script:
1. Identify purpose
2. Note language (bash, python, etc.)
3. Check if documented
Output format (JSON):
{
"script_directories": [
{
"path": "scripts/",
"script_count": 5,
"purposes": ["build", "deploy", "utility"],
"documented": true
}
],
"total_scripts": 10
}
Use Glob to find script files.
```
## Expected Output
Each task will return JSON with analysis results.
After all tasks complete, merge the results into a single repository index.
## Performance Expectations
- Sequential execution: ~300ms
- Parallel execution: ~60-100ms (3-5x faster)
- No GIL limitations (API-level parallelism)
================================================
FILE: PLANNING.md
================================================
# PLANNING.md
**Architecture, Design Principles, and Absolute Rules for SuperClaude Framework**
> This document is read by Claude Code at session start to ensure consistent, high-quality development aligned with project standards.
---
## 🎯 **Project Vision**
SuperClaude Framework transforms Claude Code into a structured development platform through:
- **Behavioral instruction injection** via CLAUDE.md
- **Component orchestration** via pytest plugin + slash commands
- **Systematic workflow automation** via PM Agent patterns
**Core Mission**: Enhance AI-assisted development with:
- Pre-execution confidence checking (prevent wrong-direction work)
- Post-implementation validation (prevent hallucinations)
- Cross-session learning (reflexion pattern)
- Token-efficient parallel execution (3.5x speedup)
---
## 🏗️ **Architecture Overview**
### **Current State (v4.2.0)**
SuperClaude is a **Python package** with:
- Pytest plugin (auto-loaded via entry points)
- CLI tools (superclaude command)
- PM Agent patterns (confidence, self-check, reflexion)
- Parallel execution framework
- Optional slash commands (installed to ~/.claude/commands/)
```
SuperClaude Framework v4.2.0
│
├── Core Package (src/superclaude/)
│ ├── pytest_plugin.py # Auto-loaded by pytest
│ ├── pm_agent/ # Pre/post implementation patterns
│ │ ├── confidence.py # Pre-execution confidence check
│ │ ├── self_check.py # Post-implementation validation
│ │ ├── reflexion.py # Error learning
│ │ └── token_budget.py # Token allocation
│ ├── execution/ # Parallel execution
│ │ ├── parallel.py # Wave→Checkpoint→Wave
│ │ ├── reflection.py # Meta-reasoning
│ │ └── self_correction.py # Error recovery
│ └── cli/ # Command-line interface
│ ├── main.py # superclaude command
│ ├── doctor.py # Health checks
│ └── install_skill.py # Skill installation
│
├── Plugin Source (plugins/superclaude/) # v5.0 - NOT ACTIVE YET
│ ├── agents/ # Agent definitions
│ ├── commands/ # Command definitions
│ ├── hooks/ # Hook configurations
│ ├── scripts/ # Shell scripts
│ └── skills/ # Skill implementations
│
├── Tests (tests/)
│ ├── unit/ # Component unit tests
│ └── integration/ # Plugin integration tests
│
└── Documentation (docs/)
├── architecture/ # Architecture decisions
├── developer-guide/ # Development guides
├── reference/ # API reference
├── research/ # Research findings
└── user-guide/ # User documentation
```
### **Future State (v5.0 - Planned)**
- TypeScript plugin system (issue #419)
- Project-local `.claude-plugin/` detection
- Plugin marketplace distribution
- Enhanced MCP server integration
---
## ⚙️ **Design Principles**
### **1. Evidence-Based Development**
**Never guess** - always verify with official sources:
- Use Context7 MCP for official documentation
- Use WebFetch/WebSearch for research
- Check existing code with Glob/Grep before implementing
- Verify assumptions against test results
**Anti-pattern**: Implementing based on assumptions or outdated knowledge
### **2. Confidence-First Implementation**
Check confidence BEFORE starting work:
- **≥90%**: Proceed with implementation
- **70-89%**: Present alternatives, continue investigation
- **<70%**: STOP - ask questions, investigate more
**ROI**: Spend 100-200 tokens on confidence check to save 5,000-50,000 tokens on wrong direction
### **3. Parallel-First Execution**
Use **Wave → Checkpoint → Wave** pattern:
```
Wave 1: [Read file1, Read file2, Read file3] (parallel)
↓
Checkpoint: Analyze all files together
↓
Wave 2: [Edit file1, Edit file2, Edit file3] (parallel)
```
**Benefit**: 3.5x faster than sequential execution
**When to use**:
- Independent operations (reading multiple files)
- Batch transformations (editing multiple files)
- Parallel searches (grep across different directories)
**When NOT to use**:
- Operations with dependencies (must wait for previous result)
- Sequential analysis (need to build context step-by-step)
### **4. Token Efficiency**
Allocate tokens based on task complexity:
- **Simple** (typo fix): 200 tokens
- **Medium** (bug fix): 1,000 tokens
- **Complex** (feature): 2,500 tokens
**Confidence check ROI**: 25-250x token savings
### **5. No Hallucinations**
Use SelfCheckProtocol to prevent hallucinations:
**The Four Questions**:
1. Are all tests passing? (show output)
2. Are all requirements met? (list items)
3. No assumptions without verification? (show docs)
4. Is there evidence? (test results, code changes, validation)
**7 Red Flags**:
- "Tests pass" without output
- "Everything works" without evidence
- "Implementation complete" with failing tests
- Skipping error messages
- Ignoring warnings
- Hiding failures
- "Probably works" language
---
## 🚫 **Absolute Rules**
### **Python Environment**
1. **ALWAYS use UV** for Python operations:
```bash
uv run pytest # NOT: python -m pytest
uv pip install package # NOT: pip install package
uv run python script.py # NOT: python script.py
```
2. **Package structure**: Use src/ layout
- `src/superclaude/` for package code
- `tests/` for test code
- Never mix source and tests in same directory
3. **Entry points**: Use pyproject.toml
- CLI: `[project.scripts]`
- Pytest plugin: `[project.entry-points.pytest11]`
### **Testing**
1. **All new features MUST have tests**
- Unit tests for individual components
- Integration tests for component interactions
- Use pytest markers: `@pytest.mark.unit`, `@pytest.mark.integration`
2. **Use PM Agent patterns in tests**:
```python
@pytest.mark.confidence_check
def test_feature(confidence_checker):
context = {...}
assert confidence_checker.assess(context) >= 0.7
@pytest.mark.self_check
def test_implementation(self_check_protocol):
passed, issues = self_check_protocol.validate(impl)
assert passed
```
3. **Test fixtures**: Use conftest.py for shared fixtures
### **Git Workflow**
1. **Branch structure**:
- `master`: Production-ready code
- `integration`: Testing ground (not yet created)
- `feature/*`, `fix/*`, `docs/*`: Feature branches
2. **Commit messages**: Use conventional commits
- `feat:` - New feature
- `fix:` - Bug fix
- `docs:` - Documentation
- `refactor:` - Code refactoring
- `test:` - Adding tests
- `chore:` - Maintenance
3. **Never commit**:
- `__pycache__/`, `*.pyc`
- `.venv/`, `venv/`
- Personal files (TODO.txt, CRUSH.md)
- API keys, secrets
### **Documentation**
1. **Code documentation**:
- All public functions need docstrings
- Use type hints
- Include usage examples in docstrings
2. **Project documentation**:
- Update CLAUDE.md for Claude Code guidance
- Update README.md for user instructions
- Update this PLANNING.md for architecture decisions
- Update TASK.md for current work
- Update KNOWLEDGE.md for insights
3. **Keep docs synchronized**:
- When code changes, update relevant docs
- When features are added, update CHANGELOG.md
- When architecture changes, update PLANNING.md
### **Version Management**
1. **Version sources of truth**:
- Framework version: `VERSION` file (e.g., 4.2.0)
- Python package version: `pyproject.toml` (e.g., 0.4.0)
- NPM package version: `package.json` (should match VERSION)
2. **When to bump versions**:
- Major: Breaking API changes
- Minor: New features, backward compatible
- Patch: Bug fixes
---
## 🔄 **Development Workflow**
### **Starting a New Feature**
1. **Investigation Phase**:
- Read PLANNING.md, TASK.md, KNOWLEDGE.md
- Check for duplicates (Glob/Grep existing code)
- Read official docs (Context7 MCP, WebFetch)
- Search for OSS implementations (WebSearch)
- Run confidence check (should be ≥90%)
2. **Implementation Phase**:
- Create feature branch: `git checkout -b feature/feature-name`
- Write tests first (TDD)
- Implement feature
- Run tests: `uv run pytest`
- Run linter: `make lint`
- Format code: `make format`
3. **Validation Phase**:
- Run self-check protocol
- Verify all tests passing
- Check all requirements met
- Confirm assumptions verified
- Provide evidence
4. **Documentation Phase**:
- Update relevant documentation
- Add docstrings
- Update CHANGELOG.md
- Update TASK.md (mark complete)
5. **Review Phase**:
- Create pull request
- Request review
- Address feedback
- Merge to integration (or master if no integration branch)
### **Fixing a Bug**
1. **Root Cause Analysis**:
- Reproduce the bug
- Identify root cause (not symptoms)
- Check reflexion memory for similar patterns
- Run confidence check
2. **Fix Implementation**:
- Write failing test that reproduces bug
- Implement fix
- Verify test passes
- Run full test suite
- Record in reflexion memory
3. **Prevention**:
- Add regression test
- Update documentation if needed
- Share learnings in KNOWLEDGE.md
---
## 📊 **Quality Metrics**
### **Code Quality**
- **Test coverage**: Aim for >80%
- **Linting**: Zero ruff errors
- **Type checking**: Use type hints, minimal mypy errors
- **Documentation**: All public APIs documented
### **PM Agent Metrics**
- **Confidence check ROI**: 25-250x token savings
- **Self-check detection**: 94% hallucination detection rate
- **Parallel execution**: 3.5x speedup vs sequential
- **Token efficiency**: 30-50% reduction with proper budgeting
### **Release Criteria**
Before releasing a new version:
- ✅ All tests passing
- ✅ Documentation updated
- ✅ CHANGELOG.md updated
- ✅ Version numbers synced
- ✅ No known critical bugs
- ✅ Security audit passed (if applicable)
---
## 🚀 **Roadmap**
### **v4.2.0 (Current)**
- ✅ Python package with pytest plugin
- ✅ PM Agent patterns (confidence, self-check, reflexion)
- ✅ Parallel execution framework
- ✅ CLI tools and slash commands
- ✅ AIRIS MCP Gateway (optional, requires Docker)
- ✅ Explicit command boundaries and handoff instructions
- ✅ Complete command reference documentation
### **v4.3.0 (Next)**
- [ ] Complete placeholder implementations in confidence.py
- [ ] Add comprehensive test coverage (>80%)
- [ ] Enhanced MCP server integration
- [ ] Improve documentation
### **v5.0 (Future)**
- [ ] TypeScript plugin system (issue #419)
- [ ] Plugin marketplace
- [ ] Project-local plugin detection
- [ ] Enhanced reflexion with mindbase integration
- [ ] Advanced parallel execution patterns
---
## 🤝 **Contributing Guidelines**
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.
**Key points**:
- Follow absolute rules above
- Write tests for all new code
- Use PM Agent patterns
- Document your changes
- Request reviews
---
## 📚 **Additional Resources**
- **[TASK.md](TASK.md)**: Current tasks and priorities
- **[KNOWLEDGE.md](KNOWLEDGE.md)**: Accumulated insights and best practices
- **[CONTRIBUTING.md](CONTRIBUTING.md)**: Contribution guidelines
- **[docs/](docs/)**: Comprehensive documentation
---
*This document is maintained by the SuperClaude development team and should be updated whenever architectural decisions are made.*
**Last updated**: 2025-11-12 (auto-generated during issue #466 fix)
================================================
FILE: PLUGIN_INSTALL.md
================================================
# 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
================================================
FILE: PROJECT_INDEX.json
================================================
{
"metadata": {
"generated_at": "2025-10-29T00:00:00Z",
"version": "0.4.0",
"total_files": 196,
"python_loc": 3002,
"test_files": 7,
"documentation_files": 90
},
"entry_points": {
"cli": {
"command": "superclaude",
"source": "src/superclaude/cli/main.py",
"purpose": "CLI interface for SuperClaude operations"
},
"pytest_plugin": {
"auto_loaded": true,
"source": "src/superclaude/pytest_plugin.py",
"purpose": "PM Agent fixtures and test automation"
},
"skills": {
"confidence_check": {
"source": ".claude/skills/confidence-check/confidence.ts",
"purpose": "Pre-implementation confidence assessment"
}
}
},
"core_modules": {
"pm_agent": {
"path": "src/superclaude/pm_agent/",
"modules": {
"confidence": {
"file": "confidence.py",
"purpose": "Pre-execution confidence assessment",
"threshold": "≥90% required, 70-89% present alternatives, <70% ask questions",
"roi": "25-250x token savings"
},
"self_check": {
"file": "self_check.py",
"purpose": "Post-implementation evidence-based validation",
"pattern": "Assert → Verify → Report"
},
"reflexion": {
"file": "reflexion.py",
"purpose": "Error learning and prevention",
"features": ["Cross-session pattern matching", "Failure analysis"]
},
"token_budget": {
"file": "token_budget.py",
"purpose": "Token allocation and tracking",
"levels": {
"simple": 200,
"medium": 1000,
"complex": 2500
}
}
}
},
"execution": {
"path": "src/superclaude/execution/",
"modules": {
"parallel": {
"file": "parallel.py",
"pattern": "Wave → Checkpoint → Wave",
"performance": "3.5x faster than sequential"
},
"reflection": {
"file": "reflection.py",
"purpose": "Post-execution analysis and improvement"
},
"self_correction": {
"file": "self_correction.py",
"purpose": "Automated error detection and correction"
}
}
},
"cli": {
"path": "src/superclaude/cli/",
"modules": {
"main": {
"file": "main.py",
"exports": ["main()"],
"framework": "Click-based CLI"
},
"doctor": {
"file": "doctor.py",
"purpose": "Health check diagnostics"
},
"install_skill": {
"file": "install_skill.py",
"purpose": "Install SuperClaude skills to Claude Code",
"target": "~/.claude/skills/"
}
}
}
},
"configuration": {
"python_package": {
"file": "pyproject.toml",
"build_system": "hatchling (PEP 517)",
"python_version": ">=3.10",
"dependencies": {
"pytest": ">=7.0.0",
"click": ">=8.0.0",
"rich": ">=13.0.0"
}
},
"npm_wrapper": {
"file": "package.json",
"package": "@bifrost_inc/superclaude",
"version": "4.1.5",
"purpose": "Cross-platform installation wrapper"
},
"claude_code": {
"file": ".claude/settings.json",
"purpose": "Plugin and marketplace settings"
}
},
"documentation": {
"key_files": [
"CLAUDE.md",
"README.md",
"CONTRIBUTING.md",
"CHANGELOG.md",
"AGENTS.md"
],
"user_guides": [
"docs/user-guide/commands.md",
"docs/user-guide/agents.md",
"docs/user-guide/flags.md",
"docs/user-guide/modes.md",
"docs/user-guide/session-management.md",
"docs/user-guide/mcp-servers.md"
],
"developer_guides": [
"docs/developer-guide/contributing-code.md",
"docs/developer-guide/technical-architecture.md",
"docs/developer-guide/testing-debugging.md"
],
"architecture": [
"docs/architecture/MIGRATION_TO_CLEAN_ARCHITECTURE.md",
"docs/architecture/PM_AGENT_COMPARISON.md",
"docs/architecture/CONTEXT_WINDOW_ANALYSIS.md"
],
"research": [
"docs/research/llm-agent-token-efficiency-2025.md",
"docs/research/reflexion-integration-2025.md",
"docs/research/parallel-execution-complete-findings.md",
"docs/research/pm_agent_roi_analysis_2025-10-21.md"
]
},
"tests": {
"framework": "pytest >=7.0.0",
"coverage_tool": "pytest-cov >=4.0.0",
"markers": [
"confidence_check",
"self_check",
"reflexion",
"unit",
"integration"
],
"test_files": [
"tests/pm_agent/test_confidence_check.py",
"tests/pm_agent/test_self_check_protocol.py",
"tests/pm_agent/test_reflexion_pattern.py",
"tests/pm_agent/test_token_budget.py",
"tests/test_pytest_plugin.py",
"tests/conftest.py"
],
"commands": {
"all_tests": "uv run pytest",
"specific_directory": "uv run pytest tests/pm_agent/ -v",
"by_marker": "uv run pytest -m confidence_check",
"with_coverage": "uv run pytest --cov=superclaude"
}
},
"dependencies": {
"core": {
"pytest": ">=7.0.0",
"click": ">=8.0.0",
"rich": ">=13.0.0"
},
"dev": {
"pytest-cov": ">=4.0.0",
"pytest-benchmark": ">=4.0.0",
"scipy": ">=1.10.0",
"ruff": ">=0.1.0",
"mypy": ">=1.0"
}
},
"quick_start": {
"installation": [
"uv pip install superclaude",
"pip install superclaude",
"make install"
],
"usage": [
"superclaude --version",
"superclaude install-skill confidence-check",
"make doctor",
"make test"
]
},
"git_workflow": {
"branch_structure": "master (production) ← integration (testing) ← feature/*, fix/*, docs/*",
"current_branch": "next"
},
"token_efficiency": {
"index_performance": {
"before": "58,000 tokens (reading all files every session)",
"after": "3,000 tokens (reading this index)",
"reduction": "94% (55,000 tokens saved per session)"
},
"pm_agent_roi": {
"confidence_check_cost": "100-200 tokens",
"savings": "5,000-50,000 tokens",
"roi": "25-250x token savings",
"break_even": "1 failed implementation prevented"
}
},
"project_stats": {
"python_source_lines": 3002,
"test_files_count": 7,
"documentation_files_count": 90,
"supported_python": ["3.10", "3.11", "3.12"],
"license": "MIT",
"contributors": 3
},
"mcp_integration": {
"servers": {
"tavily": "Web search (Deep Research)",
"context7": "Official documentation (prevent hallucination)",
"sequential": "Token-efficient reasoning (30-50% reduction)",
"serena": "Session persistence",
"mindbase": "Cross-session learning"
}
},
"project_principles": [
"Evidence-Based Development - Never guess, verify with official docs",
"Confidence-First Implementation - Check confidence BEFORE starting",
"Parallel-First Execution - Use Wave → Checkpoint → Wave (3.5x faster)",
"Token Efficiency - Optimize for minimal token usage",
"Test-Driven Development - Tests first, implementation second"
]
}
================================================
FILE: PROJECT_INDEX.md
================================================
# Project Index: SuperClaude Framework
**Generated**: 2025-10-29
**Version**: 0.4.0
**Description**: AI-enhanced development framework for Claude Code - pytest plugin with specialized commands
---
## 📁 Project Structure
```
SuperClaude_Framework/
├── src/superclaude/ # Python package (3,002 LOC)
│ ├── cli/ # CLI commands (main.py, doctor.py, install_skill.py)
│ ├── pm_agent/ # PM Agent core (confidence.py, self_check.py, reflexion.py, token_budget.py)
│ ├── execution/ # Execution patterns (parallel.py, reflection.py, self_correction.py)
│ ├── pytest_plugin.py # Auto-loaded pytest integration
│ └── skills/ # TypeScript skills (confidence-check)
├── tests/ # Test suite (7 files)
│ ├── pm_agent/ # PM Agent tests (confidence, self_check, reflexion)
│ └── conftest.py # Shared fixtures
├── docs/ # Documentation (90+ files)
│ ├── user-guide/ # User guides (en, ja, kr, zh)
│ ├── developer-guide/ # Developer documentation
│ ├── reference/ # API reference & examples
│ ├── architecture/ # Architecture decisions
│ └── research/ # Research findings
├── scripts/ # Analysis tools (workflow metrics, A/B testing)
├── setup/ # Setup components & utilities
├── skills/ # Claude Code skills
│ └── confidence-check/ # Confidence check skill (SKILL.md, confidence.ts)
├── .claude/ # Claude Code configuration
│ ├── settings.json # Plugin settings
│ └── skills/ # Installed skills
└── .github/ # GitHub workflows & templates
```
---
## 🚀 Entry Points
### CLI
- **Command**: `superclaude` (installed via pip/uv)
- **Source**: `src/superclaude/cli/main.py:main`
- **Purpose**: CLI interface for SuperClaude operations
### Pytest Plugin
- **Auto-loaded**: Yes (via `pyproject.toml` entry point)
- **Source**: `src/superclaude/pytest_plugin.py`
- **Purpose**: PM Agent fixtures and test automation
### Skills
- **Confidence Check**: `.claude/skills/confidence-check/confidence.ts`
- **Purpose**: Pre-implementation confidence assessment
---
## 📦 Core Modules
### PM Agent (src/superclaude/pm_agent/)
Core patterns for AI-enhanced development:
#### ConfidenceChecker (`confidence.py`)
- **Purpose**: Pre-execution confidence assessment
- **Threshold**: ≥90% required, 70-89% present alternatives, <70% ask questions
- **ROI**: 25-250x token savings
- **Checks**: No duplication, architecture compliance, official docs, OSS references, root cause identification
#### SelfCheckProtocol (`self_check.py`)
- **Purpose**: Post-implementation evidence-based validation
- **Approach**: No speculation - verify with tests/docs
- **Pattern**: Assert → Verify → Report
#### ReflexionPattern (`reflexion.py`)
- **Purpose**: Error learning and prevention
- **Features**: Cross-session pattern matching, failure analysis
- **Storage**: Session-persistent learning
#### TokenBudgetManager (`token_budget.py`)
- **Purpose**: Token allocation and tracking
- **Levels**: Simple (200), Medium (1,000), Complex (2,500)
- **Enforcement**: Budget-aware execution
### Execution Patterns (src/superclaude/execution/)
#### Parallel Execution (`parallel.py`)
- **Pattern**: Wave → Checkpoint → Wave
- **Performance**: 3.5x faster than sequential
- **Features**: Automatic dependency analysis, concurrent tool calls
- **Example**: [Read files in parallel] → Analyze → [Edit files in parallel]
#### Reflection (`reflection.py`)
- **Purpose**: Post-execution analysis and improvement
- **Integration**: Works with ReflexionPattern
#### Self-Correction (`self_correction.py`)
- **Purpose**: Automated error detection and correction
- **Strategy**: Iterative refinement
### CLI Commands (src/superclaude/cli/)
#### main.py
- **Exports**: `main()` - CLI entry point
- **Framework**: Click-based CLI
- **Commands**: install-skill, doctor (health check)
#### doctor.py
- **Purpose**: Health check diagnostics
- **Checks**: Package installation, pytest plugin, skills availability
#### install_skill.py
- **Purpose**: Install SuperClaude skills to Claude Code
- **Target**: `~/.claude/skills/`
---
## 🔧 Configuration
### Python Package
- **File**: `pyproject.toml`
- **Build**: hatchling (PEP 517)
- **Python**: ≥3.10
- **Dependencies**: pytest ≥7.0.0, click ≥8.0.0, rich ≥13.0.0
### NPM Wrapper
- **File**: `package.json`
- **Package**: `@bifrost_inc/superclaude`
- **Version**: 4.1.5
- **Purpose**: Cross-platform installation wrapper
### Claude Code
- **File**: `.claude/settings.json`
- **Purpose**: Plugin and marketplace settings
---
## 📚 Documentation
### Key Files
- **CLAUDE.md**: Instructions for Claude Code integration
- **README.md**: Project overview and quick start
- **CONTRIBUTING.md**: Contribution guidelines
- **CHANGELOG.md**: Version history
- **AGENTS.md**: Agent architecture documentation
### User Guides (docs/user-guide/)
- **commands.md**: Available commands
- **agents.md**: Agent usage patterns
- **flags.md**: CLI flags and options
- **modes.md**: Operation modes
- **session-management.md**: Session persistence
- **mcp-servers.md**: MCP server integration
### Developer Guides (docs/developer-guide/)
- **contributing-code.md**: Code contribution workflow
- **technical-architecture.md**: Architecture overview
- **testing-debugging.md**: Testing strategies
### Reference (docs/reference/)
- **basic-examples.md**: Usage examples
- **advanced-patterns.md**: Advanced implementation patterns
- **troubleshooting.md**: Common issues and solutions
- **diagnostic-reference.md**: Health check diagnostics
### Architecture (docs/architecture/)
- **MIGRATION_TO_CLEAN_ARCHITECTURE.md**: Architecture evolution
- **PHASE_1_COMPLETE.md**: Phase 1 migration results
- **PM_AGENT_COMPARISON.md**: PM Agent vs alternatives
- **CONTEXT_WINDOW_ANALYSIS.md**: Token efficiency analysis
### Research (docs/research/)
- **llm-agent-token-efficiency-2025.md**: Token optimization research
- **reflexion-integration-2025.md**: Reflexion pattern integration
- **parallel-execution-complete-findings.md**: Parallel execution results
- **pm_agent_roi_analysis_2025-10-21.md**: ROI analysis
---
## 🧪 Test Coverage
### Structure
- **Unit tests**: 7 files in `tests/pm_agent/`
- **Test framework**: pytest ≥7.0.0
- **Coverage tool**: pytest-cov ≥4.0.0
- **Markers**: confidence_check, self_check, reflexion, unit, integration
### Test Files
1. `test_confidence_check.py` - ConfidenceChecker tests
2. `test_self_check_protocol.py` - SelfCheckProtocol tests
3. `test_reflexion_pattern.py` - ReflexionPattern tests
4. `test_pytest_plugin.py` - Pytest plugin tests
5. `conftest.py` - Shared fixtures
### Running Tests
```bash
# All tests
uv run pytest
# Specific directory
uv run pytest tests/pm_agent/ -v
# By marker
uv run pytest -m confidence_check
# With coverage
uv run pytest --cov=superclaude
```
---
## 🔗 Key Dependencies
### Core Dependencies (pyproject.toml)
- **pytest** ≥7.0.0 - Testing framework
- **click** ≥8.0.0 - CLI framework
- **rich** ≥13.0.0 - Terminal formatting
### Dev Dependencies
- **pytest-cov** ≥4.0.0 - Coverage reporting
- **pytest-benchmark** ≥4.0.0 - Performance testing
- **scipy** ≥1.10.0 - A/B testing (statistical analysis)
- **ruff** ≥0.1.0 - Linting and formatting
- **mypy** ≥1.0 - Type checking
---
## 📝 Quick Start
### Installation
```bash
# Install with UV (recommended)
uv pip install superclaude
# Or with pip
pip install superclaude
# Development mode
make install
```
### Usage
```bash
# CLI commands
superclaude --version
superclaude install-skill confidence-check
# Health check
make doctor
# Run tests
make test
# Format and lint
make format
make lint
```
### Pytest Integration
```python
# Automatically available after installation
@pytest.mark.confidence_check
def test_feature(confidence_checker):
context = {"has_official_docs": True}
assert confidence_checker.assess(context) >= 0.9
```
---
## 🌿 Git Workflow
**Branch structure**: `master` (production) ← `integration` (testing) ← `feature/*`, `fix/*`, `docs/*`
**Current branch**: `next`
---
## 🎯 Token Efficiency
### Index Performance
- **Before**: 58,000 tokens (reading all files every session)
- **After**: 3,000 tokens (reading this index)
- **Reduction**: 94% (55,000 tokens saved per session)
### PM Agent ROI
- **Confidence check**: 100-200 tokens → saves 5,000-50,000 tokens
- **ROI**: 25-250x token savings
- **Break-even**: 1 failed implementation prevented
---
## 📊 Project Stats
- **Python source**: 3,002 lines of code
- **Test files**: 7 files
- **Documentation**: 90+ markdown files
- **Supported Python**: 3.10, 3.11, 3.12
- **License**: MIT
- **Contributors**: 3 core maintainers
---
## 🔌 MCP Server Integration
Integrates with multiple MCP servers via **airis-mcp-gateway**:
- **Tavily**: Web search (Deep Research)
- **Context7**: Official documentation (prevent hallucination)
- **Sequential**: Token-efficient reasoning (30-50% reduction)
- **Serena**: Session persistence
- **Mindbase**: Cross-session learning
---
## 🎨 Project Principles
1. **Evidence-Based Development** - Never guess, verify with official docs
2. **Confidence-First Implementation** - Check confidence BEFORE starting
3. **Parallel-First Execution** - Use Wave → Checkpoint → Wave (3.5x faster)
4. **Token Efficiency** - Optimize for minimal token usage
5. **Test-Driven Development** - Tests first, implementation second
---
**For detailed documentation**: See `docs/` directory or visit [GitHub repository](https://github.com/SuperClaude-Org/SuperClaude_Framework)
================================================
FILE: PR_DOCUMENTATION.md
================================================
# PR: PM Mode as Default - Phase 1 Implementation
**Status**: ✅ Ready for Review
**Test Coverage**: 26 tests, all passing
**Breaking Changes**: None
---
## 📋 Summary
This PR implements **Phase 1** of the PM-as-Default architecture: **PM Mode Initialization** and **Validation Infrastructure**.
### What This Enables
- ✅ **Automatic Context Contract generation** (project-specific rules)
- ✅ **Reflexion Memory system** (learning from mistakes)
- ✅ **5 Core Validators** (security, dependencies, runtime, tests, contracts)
- ✅ **Foundation for 4-phase workflow** (PLANNING/TASKLIST/DO/ACTION)
---
## 🎯 Problem Solved
### Before
- PM Mode was **optional** and rarely used
- No enforcement of project-specific rules (Kong, Infisical, .env禁止)
- Same mistakes repeated (no learning system)
- No pre-execution validation (implementations broke rules)
### After
- PM Mode **initializes automatically** at session start
- Context Contract **enforces rules** before execution
- Reflexion Memory **prevents recurring mistakes**
- Validators **block problematic code** before execution
---
## 🏗️ Architecture
### 1. PM Mode Init Hook
**Location**: `superclaude/core/pm_init/`
```python
from superclaude.core.pm_init import initialize_pm_mode
# Runs automatically at session start
init_data = initialize_pm_mode()
# Returns: Context Contract + Reflexion Memory + Project Structure
```
**Features**:
- Git repository detection
- Lightweight structure scan (paths only, no content reading)
- Context Contract auto-generation
- Reflexion Memory loading
---
### 2. Context Contract
**Location**: `docs/memory/context-contract.yaml` (auto-generated)
**Purpose**: Enforce project-specific rules
```yaml
version: 1.0.0
principles:
use_infisical_only: true
no_env_files: true
outbound_through: kong
runtime:
node:
manager: pnpm
source: lockfile-defined
validators:
- deps_exist_on_registry
- tests_must_run
- no_env_file_creation
- outbound_through_proxy
```
**Detection Logic**:
- Infisical → `no_env_files: true`
- Kong → `outbound_through: kong`
- Traefik → `outbound_through: traefik`
- pnpm-lock.yaml → `manager: pnpm`
---
### 3. Reflexion Memory
**Location**: `docs/memory/reflexion.jsonl`
**Purpose**: Learn from mistakes, prevent recurrence
```jsonl
{"ts": "2025-10-19T...", "task": "auth", "mistake": "forgot kong routing", "rule": "all services route through kong", "fix": "added kong route", "tests": ["test_kong.py"], "status": "adopted"}
```
**Features**:
- Add entries: `memory.add_entry(ReflexionEntry(...))`
- Search similar: `memory.search_similar_mistakes("kong routing")`
- Get rules: `memory.get_rules()`
---
### 4. Validators
**Location**: `superclaude/validators/`
#### ContextContractValidator
- Enforces project-specific rules
- Checks .env file creation (禁止)
- Detects hardcoded secrets
- Validates Kong/Traefik routing
#### DependencySanityValidator
- Validates package.json/pyproject.toml
- Checks package name format
- Detects version inconsistencies
#### RuntimePolicyValidator
- Validates Node.js/Python versions
- Checks engine specifications
- Ensures lockfile consistency
#### TestRunnerValidator
- Detects test files in changes
- Runs tests automatically
- Fails if tests don't pass
#### SecurityRoughcheckValidator
- Detects hardcoded secrets (Stripe, Supabase, OpenAI, Infisical)
- Blocks .env file creation
- Warns on unsafe patterns (eval, exec, shell=True)
---
## 📊 Test Coverage
**Total**: 26 tests, all passing
### PM Init Tests (11 tests)
- ✅ Git repository detection
- ✅ Structure scanning
- ✅ Context Contract generation (Infisical, Kong, Traefik)
- ✅ Runtime detection (Node, Python, pnpm, uv)
- ✅ Reflexion Memory (load, add, search)
### Validator Tests (15 tests)
- ✅ Context Contract validation
- ✅ Dependency sanity checks
- ✅ Runtime policy validation
- ✅ Security roughcheck (secrets, .env, unsafe patterns)
- ✅ Validator chain (all pass, early stop)
```bash
# Run tests
uv run pytest tests/core/pm_init/ tests/validators/ -v
# Results
============================== 26 passed in 0.08s ==============================
```
---
## 🚀 Usage
### Automatic Initialization
```python
# Session start (automatic)
from superclaude.core.pm_init import initialize_pm_mode
init_data = initialize_pm_mode()
# Returns
{
"status": "initialized",
"git_root": "/path/to/repo",
"structure": {...}, # Docker, Infra, Package managers
"context_contract": {...}, # Project-specific rules
"reflexion_memory": {
"total_entries": 5,
"rules": ["all services route through kong", ...],
"recent_mistakes": [...]
}
}
```
### Manual Validation
```python
from superclaude.validators import (
ContextContractValidator,
SecurityRoughcheckValidator,
ValidationStatus
)
# Create validator
validator = SecurityRoughcheckValidator()
# Validate changes
result = validator.validate({
"changes": {
".env": "SECRET_KEY=abc123"
}
})
# Check result
if result.failed:
print(result.message) # "CRITICAL security issues detected"
print(result.details) # {"critical": ["❌ .env file detected"]}
print(result.suggestions) # ["Remove hardcoded secrets", ...]
```
### Reflexion Memory
```python
from superclaude.core.pm_init import ReflexionMemory, ReflexionEntry
memory = ReflexionMemory(git_root)
# Add entry
entry = ReflexionEntry(
task="auth implementation",
mistake="forgot kong routing",
evidence="direct connection detected",
rule="all services must route through kong",
fix="added kong service in docker-compose.yml",
tests=["test_kong_routing.py"]
)
memory.add_entry(entry)
# Search similar mistakes
similar = memory.search_similar_mistakes("kong routing missing")
# Returns: List[ReflexionEntry] with similar past mistakes
# Get all rules
rules = memory.get_rules()
# Returns: ["all services must route through kong", ...]
```
---
## 📁 Files Added
```
superclaude/
├── core/pm_init/
│ ├── __init__.py # Exports
│ ├── init_hook.py # Main initialization
│ ├── context_contract.py # Contract generation
│ └── reflexion_memory.py # Memory management
├── validators/
│ ├── __init__.py
│ ├── base.py # Base validator classes
│ ├── context_contract.py
│ ├── dep_sanity.py
│ ├── runtime_policy.py
│ ├── test_runner.py
│ └── security_roughcheck.py
tests/
├── core/pm_init/
│ └── test_init_hook.py # 11 tests
└── validators/
└── test_validators.py # 15 tests
docs/memory/ (auto-generated)
├── context-contract.yaml
└── reflexion.jsonl
```
---
## 🔄 What's Next (Phase 2)
**Not included in this PR** (will be in Phase 2):
1. **PLANNING Phase** (`commands/pm/plan.py`)
- Generate 3-5 plans → Self-critique → Prune bad plans
2. **TASKLIST Phase** (`commands/pm/tasklist.py`)
- Break into parallel/sequential tasks
3. **DO Phase** (`commands/pm/do.py`)
- Execute with validator gates
4. **ACTION Phase** (`commands/pm/reflect.py`)
- Post-implementation reflection and learning
---
## ✅ Checklist
- [x] PM Init Hook implemented
- [x] Context Contract auto-generation
- [x] Reflexion Memory system
- [x] 5 Core Validators implemented
- [x] 26 tests written and passing
- [x] Documentation complete
- [ ] Code review
- [ ] Merge to integration branch
---
## 📚 References
1. **Reflexion: Language Agents with Verbal Reinforcement Learning** (2023)
- Self-reflection for 94% error detection rate
2. **Context7 MCP** - Pattern for project-specific configuration
3. **SuperClaude Framework** - Behavioral Rules and Principles
---
**Review Ready**: This PR establishes the foundation for PM-as-Default. All tests pass, no breaking changes.
================================================
FILE: QUALITY_COMPARISON.md
================================================
# Quality Comparison: Python vs TypeScript Implementation
**Date**: 2025-10-21
**Status**: ✅ **TypeScript version matches or exceeds Python quality**
---
## Executive Summary
TypeScript implementation has been verified to match or exceed the Python version's quality through comprehensive testing and evidence-based validation.
### Verdict: ✅ TypeScript >= Python Quality
- **Feature Completeness**: 100% (all 3 core patterns implemented)
- **Test Coverage**: 95.26% statement coverage, 100% function coverage
- **Test Results**: 53/53 tests passed (100% pass rate)
- **Quality**: TypeScript version is production-ready
---
## Feature Completeness Comparison
| Feature | Python | TypeScript | Status |
|---------|--------|------------|--------|
| **ConfidenceChecker** | ✅ | ✅ | Equal |
| **SelfCheckProtocol** | ✅ | ✅ | Equal |
| **ReflexionPattern** | ✅ | ✅ | Equal |
| **Token Budget Manager** | ✅ | ❌ (Python only) | N/A* |
*Note: TokenBudgetManager is a pytest-specific fixture, not needed in TypeScript plugin
---
## Test Results Comparison
### Python Version
```
Platform: darwin -- Python 3.14.0, pytest-8.4.2
Tests: 56 passed, 1 warning
Time: 0.06s
```
**Test Breakdown**:
- `test_confidence_check.py`: 18 tests ✅
- `test_self_check_protocol.py`: 18 tests ✅
- `test_reflexion_pattern.py`: 20 tests ✅
### TypeScript Version
```
Platform: Node.js 18+, Jest 30.2.0, TypeScript 5.9.3
Tests: 53 passed
Time: 4.414s
```
**Test Breakdown**:
- `confidence.test.ts`: 18 tests ✅
- `self-check.test.ts`: 21 tests ✅
- `reflexion.test.ts`: 14 tests ✅
**Code Coverage**:
```
---------------|---------|----------|---------|---------|
File | % Stmts | % Branch | % Funcs | % Lines |
---------------|-
gitextract_7b9g1o94/
├── .claude/
│ ├── settings.json
│ └── skills/
│ └── confidence-check/
│ ├── SKILL.md
│ └── confidence.ts
├── .github/
│ ├── FUNDING.yml
│ ├── PULL_REQUEST_TEMPLATE.md
│ └── workflows/
│ ├── README.md
│ ├── publish-pypi.yml
│ ├── pull-sync-framework.yml
│ ├── quick-check.yml
│ ├── readme-quality-check.yml
│ └── test.yml
├── .gitignore
├── .pre-commit-config.yaml
├── AGENTS.md
├── CHANGELOG.md
├── CLAUDE.md
├── CODEOWNERS
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── DELETION_RATIONALE.md
├── KNOWLEDGE.md
├── LICENSE
├── MANIFEST.in
├── Makefile
├── PARALLEL_INDEXING_PLAN.md
├── PLANNING.md
├── PLUGIN_INSTALL.md
├── PROJECT_INDEX.json
├── PROJECT_INDEX.md
├── PR_DOCUMENTATION.md
├── QUALITY_COMPARISON.md
├── README-ja.md
├── README-kr.md
├── README-zh.md
├── README.md
├── SECURITY.md
├── TASK.md
├── TEST_PLUGIN.md
├── VERSION
├── docs/
│ ├── Development/
│ │ ├── ARCHITECTURE.md
│ │ ├── PROJECT_STATUS.md
│ │ ├── ROADMAP.md
│ │ ├── TASKS.md
│ │ ├── hypothesis-pm-autonomous-enhancement-2025-10-14.md
│ │ ├── installation-flow-understanding.md
│ │ ├── pm-agent-ideal-workflow.md
│ │ ├── pm-agent-integration.md
│ │ ├── project-structure-understanding.md
│ │ └── tasks/
│ │ └── current-tasks.md
│ ├── PR_STRATEGY.md
│ ├── README.md
│ ├── Templates/
│ │ └── __init__.py
│ ├── agents/
│ │ └── pm-agent-guide.md
│ ├── architecture/
│ │ ├── CONTEXT_WINDOW_ANALYSIS.md
│ │ ├── MIGRATION_TO_CLEAN_ARCHITECTURE.md
│ │ ├── PHASE_1_COMPLETE.md
│ │ ├── PHASE_2_COMPLETE.md
│ │ ├── PHASE_3_COMPLETE.md
│ │ ├── PM_AGENT_COMPARISON.md
│ │ ├── SKILLS_CLEANUP.md
│ │ ├── pm-agent-auto-activation.md
│ │ └── pm-agent-responsibility-cleanup.md
│ ├── capability-mapping-v5.md
│ ├── developer-guide/
│ │ ├── README.md
│ │ ├── contributing-code.md
│ │ ├── documentation-index.md
│ │ ├── technical-architecture.md
│ │ └── testing-debugging.md
│ ├── getting-started/
│ │ ├── installation.md
│ │ └── quick-start.md
│ ├── mcp/
│ │ ├── mcp-integration-policy.md
│ │ └── mcp-optional-design.md
│ ├── memory/
│ │ ├── README.md
│ │ ├── WORKFLOW_METRICS_SCHEMA.md
│ │ ├── last_session.md
│ │ ├── next_actions.md
│ │ ├── patterns_learned.jsonl
│ │ ├── pm_context.md
│ │ ├── reflexion.jsonl.example
│ │ ├── solutions_learned.jsonl
│ │ ├── token_efficiency_validation.md
│ │ └── workflow_metrics.jsonl
│ ├── mistakes/
│ │ ├── test_database_connection-2025-11-11.md
│ │ ├── test_database_connection-2025-11-14.md
│ │ ├── test_reflexion_with_real_exception-2025-11-11.md
│ │ ├── test_reflexion_with_real_exception-2025-11-14.md
│ │ ├── unknown-2025-11-11.md
│ │ └── unknown-2025-11-14.md
│ ├── next-refactor-plan.md
│ ├── plugin-reorg.md
│ ├── pm-agent-implementation-status.md
│ ├── reference/
│ │ ├── README.md
│ │ ├── advanced-patterns.md
│ │ ├── advanced-workflows.md
│ │ ├── basic-examples.md
│ │ ├── claude-code-history-management.md
│ │ ├── commands-list.md
│ │ ├── common-issues.md
│ │ ├── comprehensive-features.md
│ │ ├── diagnostic-reference.md
│ │ ├── examples-cookbook.md
│ │ ├── integration-patterns.md
│ │ ├── mcp-server-guide.md
│ │ ├── pm-agent-autonomous-reflection.md
│ │ ├── suggested-commands.md
│ │ └── troubleshooting.md
│ ├── research/
│ │ ├── complete-python-skills-migration.md
│ │ ├── intelligent-execution-architecture.md
│ │ ├── llm-agent-token-efficiency-2025.md
│ │ ├── markdown-to-python-migration-plan.md
│ │ ├── mcp-installer-fix-summary.md
│ │ ├── parallel-execution-complete-findings.md
│ │ ├── parallel-execution-findings.md
│ │ ├── phase1-implementation-strategy.md
│ │ ├── pm-mode-performance-analysis.md
│ │ ├── pm-mode-validation-methodology.md
│ │ ├── pm-skills-migration-results.md
│ │ ├── pm_agent_roi_analysis_2025-10-21.md
│ │ ├── python_src_layout_research_20251021.md
│ │ ├── reflexion-integration-2025.md
│ │ ├── repository-understanding-proposal.md
│ │ ├── research_git_branch_integration_2025.md
│ │ ├── research_installer_improvements_20251017.md
│ │ ├── research_oss_fork_workflow_2025.md
│ │ ├── research_python_directory_naming_20251015.md
│ │ ├── research_python_directory_naming_automation_2025.md
│ │ ├── research_repository_scoped_memory_2025-10-16.md
│ │ ├── research_serena_mcp_2025-01-16.md
│ │ ├── skills-migration-test.md
│ │ └── task-tool-parallel-execution-results.md
│ ├── sessions/
│ │ └── 2025-10-14-summary.md
│ ├── testing/
│ │ ├── pm-workflow-test-results.md
│ │ └── procedures.md
│ ├── troubleshooting/
│ │ └── serena-installation.md
│ ├── user-guide/
│ │ ├── agents.md
│ │ ├── commands.md
│ │ ├── flags.md
│ │ ├── mcp-installation.md
│ │ ├── mcp-servers.md
│ │ ├── memory-system.md
│ │ ├── modes.md
│ │ └── session-management.md
│ ├── user-guide-jp/
│ │ ├── agents.md
│ │ ├── commands.md
│ │ ├── flags.md
│ │ ├── mcp-servers.md
│ │ ├── modes.md
│ │ └── session-management.md
│ ├── user-guide-kr/
│ │ ├── agents.md
│ │ ├── commands.md
│ │ ├── flags.md
│ │ ├── mcp-servers.md
│ │ ├── modes.md
│ │ └── session-management.md
│ └── user-guide-zh/
│ ├── agents.md
│ ├── commands.md
│ ├── flags.md
│ ├── mcp-servers.md
│ ├── modes.md
│ └── session-management.md
├── install.sh
├── package.json
├── plugins/
│ └── superclaude/
│ ├── __init__.py
│ ├── agents/
│ │ ├── __init__.py
│ │ ├── backend-architect.md
│ │ ├── business-panel-experts.md
│ │ ├── deep-research-agent.md
│ │ ├── deep-research.md
│ │ ├── devops-architect.md
│ │ ├── frontend-architect.md
│ │ ├── learning-guide.md
│ │ ├── performance-engineer.md
│ │ ├── pm-agent.md
│ │ ├── python-expert.md
│ │ ├── quality-engineer.md
│ │ ├── refactoring-expert.md
│ │ ├── repo-index.md
│ │ ├── requirements-analyst.md
│ │ ├── root-cause-analyst.md
│ │ ├── security-engineer.md
│ │ ├── self-review.md
│ │ ├── socratic-mentor.md
│ │ ├── system-architect.md
│ │ └── technical-writer.md
│ ├── commands/
│ │ ├── __init__.py
│ │ ├── agent.md
│ │ ├── analyze.md
│ │ ├── brainstorm.md
│ │ ├── build.md
│ │ ├── business-panel.md
│ │ ├── cleanup.md
│ │ ├── design.md
│ │ ├── document.md
│ │ ├── estimate.md
│ │ ├── explain.md
│ │ ├── git.md
│ │ ├── help.md
│ │ ├── implement.md
│ │ ├── improve.md
│ │ ├── index-repo.md
│ │ ├── index.md
│ │ ├── load.md
│ │ ├── pm.md
│ │ ├── recommend.md
│ │ ├── reflect.md
│ │ ├── research.md
│ │ ├── save.md
│ │ ├── sc.md
│ │ ├── select-tool.md
│ │ ├── spawn.md
│ │ ├── spec-panel.md
│ │ ├── task.md
│ │ ├── test.md
│ │ ├── troubleshoot.md
│ │ └── workflow.md
│ ├── core/
│ │ ├── BUSINESS_PANEL_EXAMPLES.md
│ │ ├── BUSINESS_SYMBOLS.md
│ │ ├── FLAGS.md
│ │ ├── PRINCIPLES.md
│ │ ├── RESEARCH_CONFIG.md
│ │ ├── RULES.md
│ │ └── __init__.py
│ ├── examples/
│ │ ├── __init__.py
│ │ └── deep_research_workflows.md
│ ├── hooks/
│ │ ├── __init__.py
│ │ └── hooks.json
│ ├── mcp/
│ │ ├── MCP_Chrome-DevTools.md
│ │ ├── MCP_Context7.md
│ │ ├── MCP_Magic.md
│ │ ├── MCP_Morphllm.md
│ │ ├── MCP_Playwright.md
│ │ ├── MCP_Sequential.md
│ │ ├── MCP_Serena.md
│ │ ├── MCP_Tavily.md
│ │ ├── __init__.py
│ │ └── configs/
│ │ ├── __init__.py
│ │ ├── context7.json
│ │ ├── magic.json
│ │ ├── morphllm.json
│ │ ├── playwright.json
│ │ ├── sequential.json
│ │ ├── serena-docker.json
│ │ ├── serena.json
│ │ └── tavily.json
│ ├── modes/
│ │ ├── MODE_Brainstorming.md
│ │ ├── MODE_Business_Panel.md
│ │ ├── MODE_DeepResearch.md
│ │ ├── MODE_Introspection.md
│ │ ├── MODE_Orchestration.md
│ │ ├── MODE_Task_Management.md
│ │ ├── MODE_Token_Efficiency.md
│ │ └── __init__.py
│ ├── scripts/
│ │ ├── __init__.py
│ │ ├── clean_command_names.py
│ │ └── session-init.sh
│ └── skills/
│ ├── __init__.py
│ └── confidence-check/
│ ├── SKILL.md
│ ├── __init__.py
│ └── confidence.ts
├── pyproject.toml
├── scripts/
│ ├── README.md
│ ├── ab_test_workflows.py
│ ├── analyze_workflow_metrics.py
│ ├── build_superclaude_plugin.py
│ ├── cleanup.sh
│ ├── publish.sh
│ ├── sync_from_framework.py
│ └── uninstall_legacy.sh
├── setup.py
├── skills/
│ └── confidence-check/
│ ├── SKILL.md
│ └── confidence.ts
├── src/
│ └── superclaude/
│ ├── __init__.py
│ ├── __version__.py
│ ├── agents/
│ │ ├── README.md
│ │ ├── __init__.py
│ │ ├── backend-architect.md
│ │ ├── business-panel-experts.md
│ │ ├── deep-research-agent.md
│ │ ├── deep-research.md
│ │ ├── devops-architect.md
│ │ ├── frontend-architect.md
│ │ ├── learning-guide.md
│ │ ├── performance-engineer.md
│ │ ├── pm-agent.md
│ │ ├── python-expert.md
│ │ ├── quality-engineer.md
│ │ ├── refactoring-expert.md
│ │ ├── repo-index.md
│ │ ├── requirements-analyst.md
│ │ ├── root-cause-analyst.md
│ │ ├── security-engineer.md
│ │ ├── self-review.md
│ │ ├── socratic-mentor.md
│ │ ├── system-architect.md
│ │ └── technical-writer.md
│ ├── cli/
│ │ ├── __init__.py
│ │ ├── doctor.py
│ │ ├── install_commands.py
│ │ ├── install_mcp.py
│ │ ├── install_skill.py
│ │ └── main.py
│ ├── commands/
│ │ ├── README.md
│ │ ├── __init__.py
│ │ ├── agent.md
│ │ ├── analyze.md
│ │ ├── brainstorm.md
│ │ ├── build.md
│ │ ├── business-panel.md
│ │ ├── cleanup.md
│ │ ├── design.md
│ │ ├── document.md
│ │ ├── estimate.md
│ │ ├── explain.md
│ │ ├── git.md
│ │ ├── help.md
│ │ ├── implement.md
│ │ ├── improve.md
│ │ ├── index-repo.md
│ │ ├── index.md
│ │ ├── load.md
│ │ ├── pm.md
│ │ ├── recommend.md
│ │ ├── reflect.md
│ │ ├── research.md
│ │ ├── save.md
│ │ ├── sc.md
│ │ ├── select-tool.md
│ │ ├── spawn.md
│ │ ├── spec-panel.md
│ │ ├── task.md
│ │ ├── test.md
│ │ ├── troubleshoot.md
│ │ └── workflow.md
│ ├── core/
│ │ ├── BUSINESS_PANEL_EXAMPLES.md
│ │ ├── BUSINESS_SYMBOLS.md
│ │ ├── FLAGS.md
│ │ ├── PRINCIPLES.md
│ │ ├── RESEARCH_CONFIG.md
│ │ ├── RULES.md
│ │ └── __init__.py
│ ├── examples/
│ │ ├── __init__.py
│ │ └── deep_research_workflows.md
│ ├── execution/
│ │ ├── __init__.py
│ │ ├── parallel.py
│ │ ├── reflection.py
│ │ └── self_correction.py
│ ├── hooks/
│ │ ├── README.md
│ │ ├── __init__.py
│ │ └── hooks.json
│ ├── mcp/
│ │ ├── MCP_Airis-Agent.md
│ │ ├── MCP_Chrome-DevTools.md
│ │ ├── MCP_Context7.md
│ │ ├── MCP_Magic.md
│ │ ├── MCP_Mindbase.md
│ │ ├── MCP_Morphllm.md
│ │ ├── MCP_Playwright.md
│ │ ├── MCP_Sequential.md
│ │ ├── MCP_Serena.md
│ │ ├── MCP_Tavily.md
│ │ ├── __init__.py
│ │ └── configs/
│ │ ├── __init__.py
│ │ ├── airis-agent.json
│ │ ├── context7.json
│ │ ├── magic.json
│ │ ├── mindbase.json
│ │ ├── morphllm.json
│ │ ├── playwright.json
│ │ ├── sequential.json
│ │ ├── serena-docker.json
│ │ ├── serena.json
│ │ └── tavily.json
│ ├── modes/
│ │ ├── MODE_Brainstorming.md
│ │ ├── MODE_Business_Panel.md
│ │ ├── MODE_DeepResearch.md
│ │ ├── MODE_Introspection.md
│ │ ├── MODE_Orchestration.md
│ │ ├── MODE_Task_Management.md
│ │ ├── MODE_Token_Efficiency.md
│ │ └── __init__.py
│ ├── pm_agent/
│ │ ├── __init__.py
│ │ ├── confidence.py
│ │ ├── reflexion.py
│ │ ├── self_check.py
│ │ └── token_budget.py
│ ├── pytest_plugin.py
│ ├── scripts/
│ │ ├── README.md
│ │ ├── __init__.py
│ │ ├── clean_command_names.py
│ │ └── session-init.sh
│ └── skills/
│ ├── __init__.py
│ └── confidence-check/
│ ├── SKILL.md
│ ├── __init__.py
│ └── confidence.ts
└── tests/
├── __init__.py
├── conftest.py
├── integration/
│ ├── __init__.py
│ └── test_pytest_plugin.py
└── unit/
├── __init__.py
├── test_cli_install.py
├── test_confidence.py
├── test_reflexion.py
├── test_self_check.py
└── test_token_budget.py
SYMBOL INDEX (327 symbols across 31 files)
FILE: .claude/skills/confidence-check/confidence.ts
type Context (line 13) | interface Context {
function confidenceCheck (line 37) | async function confidenceCheck(context: Context): Promise<number> {
function noDuplicates (line 100) | function noDuplicates(context: Context): boolean {
function architectureCompliant (line 112) | function architectureCompliant(context: Context): boolean {
function hasOfficialDocs (line 122) | function hasOfficialDocs(context: Context): boolean {
function hasOssReference (line 141) | function hasOssReference(context: Context): boolean {
function rootCauseIdentified (line 153) | function rootCauseIdentified(context: Context): boolean {
function getRecommendation (line 163) | function getRecommendation(confidence: number): string {
FILE: plugins/superclaude/scripts/clean_command_names.py
function find_project_root (line 23) | def find_project_root() -> Path:
function clean_name_attributes (line 45) | def clean_name_attributes(content: str) -> Tuple[str, bool]:
function process_commands_directory (line 75) | def process_commands_directory(commands_dir: Path) -> int:
function main (line 128) | def main() -> int:
FILE: plugins/superclaude/skills/confidence-check/confidence.ts
type Context (line 24) | interface Context {
class ConfidenceChecker (line 53) | class ConfidenceChecker {
method assess (line 67) | async assess(context: Context): Promise<number> {
method hasOfficialDocs (line 130) | private hasOfficialDocs(context: Context): boolean {
method noDuplicates (line 176) | private noDuplicates(context: Context): boolean {
method architectureCompliant (line 194) | private architectureCompliant(context: Context): boolean {
method hasOssReference (line 212) | private hasOssReference(context: Context): boolean {
method rootCauseIdentified (line 230) | private rootCauseIdentified(context: Context): boolean {
method hasExistingPatterns (line 246) | private hasExistingPatterns(context: Context): boolean {
method hasClearPath (line 278) | private hasClearPath(context: Context): boolean {
method getRecommendation (line 303) | getRecommendation(confidence: number): string {
function confidenceCheck (line 319) | async function confidenceCheck(context: Context): Promise<number> {
function getRecommendation (line 329) | function getRecommendation(confidence: number): string {
FILE: scripts/ab_test_workflows.py
class ABTestAnalyzer (line 23) | class ABTestAnalyzer:
method __init__ (line 26) | def __init__(self, metrics_file: Path):
method _load_metrics (line 31) | def _load_metrics(self):
method get_variant_metrics (line 42) | def get_variant_metrics(self, workflow_id: str) -> List[Dict]:
method extract_metric_values (line 46) | def extract_metric_values(self, metrics: List[Dict], metric: str) -> L...
method calculate_statistics (line 58) | def calculate_statistics(self, values: List[float]) -> Dict:
method perform_ttest (line 79) | def perform_ttest(
method determine_winner (line 96) | def determine_winner(
method generate_recommendation (line 144) | def generate_recommendation(
method compare_variants (line 169) | def compare_variants(
function main (line 261) | def main():
FILE: scripts/analyze_workflow_metrics.py
class WorkflowMetricsAnalyzer (line 22) | class WorkflowMetricsAnalyzer:
method __init__ (line 25) | def __init__(self, metrics_file: Path):
method _load_metrics (line 30) | def _load_metrics(self):
method filter_by_period (line 43) | def filter_by_period(self, period: str) -> List[Dict]:
method analyze_by_task_type (line 64) | def analyze_by_task_type(self, metrics: List[Dict]) -> Dict:
method analyze_by_complexity (line 83) | def analyze_by_complexity(self, metrics: List[Dict]) -> Dict:
method analyze_by_workflow (line 101) | def analyze_by_workflow(self, metrics: List[Dict]) -> Dict:
method identify_best_workflows (line 120) | def identify_best_workflows(self, metrics: List[Dict]) -> Dict[str, str]:
method identify_inefficiencies (line 148) | def identify_inefficiencies(self, metrics: List[Dict]) -> List[Dict]:
method calculate_token_savings (line 188) | def calculate_token_savings(self, metrics: List[Dict]) -> Dict:
method generate_report (line 216) | def generate_report(self, period: str) -> str:
function main (line 297) | def main():
FILE: scripts/build_superclaude_plugin.py
function load_metadata (line 21) | def load_metadata() -> dict:
function render_template (line 36) | def render_template(template_path: Path, placeholders: dict[str, str]) -...
function copy_tree (line 44) | def copy_tree(src: Path, dest: Path) -> None:
function main (line 50) | def main() -> None:
FILE: scripts/sync_from_framework.py
class ProtectionViolationError (line 42) | class ProtectionViolationError(RuntimeError):
class SyncResult (line 48) | class SyncResult:
method to_dict (line 62) | def to_dict(self) -> dict:
class ContentTransformer (line 66) | class ContentTransformer:
method transform_command (line 76) | def transform_command(content: str, filename: str) -> str:
method transform_agent (line 115) | def transform_agent(content: str, filename: str) -> str:
class FileSyncer (line 166) | class FileSyncer:
method __init__ (line 169) | def __init__(self, plugin_root: Path, dry_run: bool = False):
method _check_git (line 174) | def _check_git(self) -> bool:
method sync_directory (line 188) | def sync_directory(
method _git_mv (line 265) | def _git_mv(self, old_path: Path, new_path: Path):
method copy_directory (line 284) | def copy_directory(self, source_dir: Path, dest_dir: Path) -> int:
class PluginJsonGenerator (line 317) | class PluginJsonGenerator:
method __init__ (line 320) | def __init__(self, plugin_root: Path):
method generate (line 323) | def generate(self, framework_version: str) -> dict:
method write (line 373) | def write(self, plugin_json: dict, dry_run: bool = False):
class McpMerger (line 390) | class McpMerger:
method __init__ (line 393) | def __init__(self, plugin_root: Path):
method merge (line 396) | def merge(
method backup_current (line 439) | def backup_current(self) -> Optional[Path]:
class FrameworkSyncer (line 457) | class FrameworkSyncer:
method __init__ (line 503) | def __init__(
method sync (line 516) | def sync(self) -> SyncResult:
method _hash_file (line 604) | def _hash_file(path: Path) -> str:
method _snapshot_protected_files (line 610) | def _snapshot_protected_files(self) -> Dict[str, str]:
method _validate_protected_files (line 633) | def _validate_protected_files(self, snapshot: Dict[str, str]) -> None:
method _clone_framework (line 665) | def _clone_framework(self) -> Path:
method _get_commit_hash (line 686) | def _get_commit_hash(self, repo_path: Path) -> str:
method _get_version (line 700) | def _get_version(self, framework_path: Path) -> str:
method _create_backup (line 724) | def _create_backup(self):
method _sync_content (line 734) | def _sync_content(self, framework_path: Path) -> Dict[str, int]:
method _generate_plugin_json (line 788) | def _generate_plugin_json(self, framework_version: str):
method _merge_mcp_configs (line 796) | def _merge_mcp_configs(self, framework_path: Path) -> int:
method _validate_sync (line 843) | def _validate_sync(self):
method _cleanup (line 866) | def _cleanup(self):
function main (line 873) | def main():
FILE: skills/confidence-check/confidence.ts
type Context (line 24) | interface Context {
class ConfidenceChecker (line 53) | class ConfidenceChecker {
method assess (line 67) | async assess(context: Context): Promise<number> {
method hasOfficialDocs (line 130) | private hasOfficialDocs(context: Context): boolean {
method noDuplicates (line 176) | private noDuplicates(context: Context): boolean {
method architectureCompliant (line 194) | private architectureCompliant(context: Context): boolean {
method hasOssReference (line 212) | private hasOssReference(context: Context): boolean {
method rootCauseIdentified (line 230) | private rootCauseIdentified(context: Context): boolean {
method hasExistingPatterns (line 246) | private hasExistingPatterns(context: Context): boolean {
method hasClearPath (line 278) | private hasClearPath(context: Context): boolean {
method getRecommendation (line 303) | getRecommendation(confidence: number): string {
function confidenceCheck (line 319) | async function confidenceCheck(context: Context): Promise<number> {
function getRecommendation (line 329) | function getRecommendation(confidence: number): string {
FILE: src/superclaude/cli/doctor.py
function run_doctor (line 11) | def run_doctor(verbose: bool = False) -> Dict[str, Any]:
function _check_pytest_plugin (line 41) | def _check_pytest_plugin() -> Dict[str, Any]:
function _check_skills_installed (line 88) | def _check_skills_installed() -> Dict[str, Any]:
function _check_configuration (line 124) | def _check_configuration() -> Dict[str, Any]:
FILE: src/superclaude/cli/install_commands.py
function install_commands (line 12) | def install_commands(target_path: Path = None, force: bool = False) -> T...
function _get_commands_source (line 92) | def _get_commands_source() -> Path:
function list_available_commands (line 125) | def list_available_commands() -> List[str]:
function list_installed_commands (line 145) | def list_installed_commands() -> List[str]:
FILE: src/superclaude/cli/install_mcp.py
function _run_command (line 95) | def _run_command(cmd: List[str], **kwargs) -> subprocess.CompletedProcess:
function check_docker_available (line 127) | def check_docker_available() -> bool:
function install_airis_gateway (line 138) | def install_airis_gateway(dry_run: bool = False) -> bool:
function check_prerequisites (line 394) | def check_prerequisites() -> Tuple[bool, List[str]]:
function check_mcp_server_installed (line 441) | def check_mcp_server_installed(server_name: str) -> bool:
function prompt_for_api_key (line 463) | def prompt_for_api_key(
function install_mcp_server (line 487) | def install_mcp_server(
function list_available_servers (line 573) | def list_available_servers():
function install_mcp_servers (line 610) | def install_mcp_servers(
FILE: src/superclaude/cli/install_skill.py
function install_skill_command (line 12) | def install_skill_command(
function _get_skill_source (line 58) | def _get_skill_source(skill_name: str) -> Optional[Path]:
function _is_valid_skill_dir (line 99) | def _is_valid_skill_dir(path: Path) -> bool:
function list_available_skills (line 115) | def list_available_skills() -> list[str]:
FILE: src/superclaude/cli/main.py
function main (line 20) | def main():
function install (line 46) | def install(target: str, force: bool, list_only: bool):
function mcp (line 106) | def mcp(servers, list_only, scope, dry_run):
function update (line 143) | def update(target: str):
function install_skill (line 181) | def install_skill(skill_name: str, target: str, force: bool):
function doctor (line 214) | def doctor(verbose: bool):
function version (line 251) | def version():
FILE: src/superclaude/execution/__init__.py
function intelligent_execute (line 41) | def intelligent_execute(
function quick_execute (line 194) | def quick_execute(operations: List[Callable]) -> List[Any]:
function safe_execute (line 213) | def safe_execute(task: str, operation: Callable, context: Optional[Dict]...
FILE: src/superclaude/execution/parallel.py
class TaskStatus (line 21) | class TaskStatus(Enum):
class Task (line 31) | class Task:
method can_execute (line 42) | def can_execute(self, completed_tasks: Set[str]) -> bool:
class ParallelGroup (line 48) | class ParallelGroup:
method __repr__ (line 55) | def __repr__(self) -> str:
class ExecutionPlan (line 60) | class ExecutionPlan:
method __repr__ (line 69) | def __repr__(self) -> str:
class ParallelExecutor (line 80) | class ParallelExecutor:
method __init__ (line 100) | def __init__(self, max_workers: int = 10):
method plan (line 103) | def plan(self, tasks: List[Task]) -> ExecutionPlan:
method execute (line 169) | def execute(self, plan: ExecutionPlan) -> Dict[str, Any]:
method _execute_group (line 204) | def _execute_group(self, group: ParallelGroup) -> Dict[str, Any]:
function parallel_file_operations (line 240) | def parallel_file_operations(files: List[str], operation: Callable) -> L...
function should_parallelize (line 269) | def should_parallelize(items: List[Any], threshold: int = 3) -> bool:
function example_parallel_read (line 281) | def example_parallel_read():
function example_dependent_tasks (line 304) | def example_dependent_tasks():
FILE: src/superclaude/execution/reflection.py
class ReflectionResult (line 20) | class ReflectionResult:
method __repr__ (line 28) | def __repr__(self) -> str:
class ConfidenceScore (line 34) | class ConfidenceScore:
method __repr__ (line 50) | def __repr__(self) -> str:
class ReflectionEngine (line 60) | class ReflectionEngine:
method __init__ (line 75) | def __init__(self, repo_path: Path):
method reflect (line 90) | def reflect(
method _reflect_clarity (line 156) | def _reflect_clarity(
method _reflect_mistakes (line 222) | def _reflect_mistakes(
method _reflect_context (line 283) | def _reflect_context(
method record_reflection (line 343) | def record_reflection(self, task: str, confidence: ConfidenceScore, de...
function get_reflection_engine (line 378) | def get_reflection_engine(repo_path: Optional[Path] = None) -> Reflectio...
function reflect_before_execution (line 391) | def reflect_before_execution(
FILE: src/superclaude/execution/self_correction.py
class RootCause (line 24) | class RootCause:
method __repr__ (line 33) | def __repr__(self) -> str:
class FailureEntry (line 43) | class FailureEntry:
method to_dict (line 56) | def to_dict(self) -> dict:
method from_dict (line 63) | def from_dict(cls, data: dict) -> "FailureEntry":
class SelfCorrectionEngine (line 70) | class SelfCorrectionEngine:
method __init__ (line 82) | def __init__(self, repo_path: Path):
method _init_reflexion_memory (line 93) | def _init_reflexion_memory(self):
method detect_failure (line 106) | def detect_failure(self, execution_result: Dict[str, Any]) -> bool:
method analyze_root_cause (line 115) | def analyze_root_cause(self, task: str, failure: Dict[str, Any]) -> Ro...
method _categorize_failure (line 157) | def _categorize_failure(self, error_msg: str, stack_trace: str) -> str:
method _find_similar_failures (line 188) | def _find_similar_failures(self, task: str, error_msg: str) -> List[Fa...
method _generate_prevention_rule (line 220) | def _generate_prevention_rule(
method _generate_validation_tests (line 242) | def _generate_validation_tests(self, category: str, error_msg: str) ->...
method learn_and_prevent (line 275) | def learn_and_prevent(
method get_prevention_rules (line 343) | def get_prevention_rules(self) -> List[str]:
method check_against_past_mistakes (line 355) | def check_against_past_mistakes(self, task: str) -> List[FailureEntry]:
function get_self_correction_engine (line 391) | def get_self_correction_engine(
function learn_from_failure (line 406) | def learn_from_failure(
FILE: src/superclaude/pm_agent/confidence.py
class ConfidenceChecker (line 26) | class ConfidenceChecker:
method assess (line 42) | def assess(self, context: Dict[str, Any]) -> float:
method _has_official_docs (line 102) | def _has_official_docs(self, context: Dict[str, Any]) -> bool:
method _no_duplicates (line 133) | def _no_duplicates(self, context: Dict[str, Any]) -> bool:
method _architecture_compliant (line 151) | def _architecture_compliant(self, context: Dict[str, Any]) -> bool:
method _has_oss_reference (line 169) | def _has_oss_reference(self, context: Dict[str, Any]) -> bool:
method _root_cause_identified (line 187) | def _root_cause_identified(self, context: Dict[str, Any]) -> bool:
method _has_existing_patterns (line 205) | def _has_existing_patterns(self, context: Dict[str, Any]) -> bool:
method _has_clear_path (line 228) | def _has_clear_path(self, context: Dict[str, Any]) -> bool:
method get_recommendation (line 257) | def get_recommendation(self, confidence: float) -> str:
FILE: src/superclaude/pm_agent/reflexion.py
class ReflexionPattern (line 32) | class ReflexionPattern:
method __init__ (line 56) | def __init__(self, memory_dir: Optional[Path] = None):
method get_solution (line 76) | def get_solution(self, error_info: Dict[str, Any]) -> Optional[Dict[st...
method record_error (line 102) | def record_error(self, error_info: Dict[str, Any]) -> None:
method _create_error_signature (line 130) | def _create_error_signature(self, error_info: Dict[str, Any]) -> str:
method _search_mindbase (line 164) | def _search_mindbase(self, error_signature: str) -> Optional[Dict[str,...
method _search_local_files (line 178) | def _search_local_files(self, error_signature: str) -> Optional[Dict[s...
method _signatures_match (line 213) | def _signatures_match(self, sig1: str, sig2: str, threshold: float = 0...
method _create_mistake_doc (line 238) | def _create_mistake_doc(self, error_info: Dict[str, Any]) -> None:
method get_statistics (line 310) | def get_statistics(self) -> Dict[str, Any]:
FILE: src/superclaude/pm_agent/self_check.py
class SelfCheckProtocol (line 19) | class SelfCheckProtocol:
method validate (line 64) | def validate(self, implementation: Dict[str, Any]) -> Tuple[bool, List...
method _check_tests_passing (line 109) | def _check_tests_passing(self, impl: Dict[str, Any]) -> bool:
method _check_requirements_met (line 129) | def _check_requirements_met(self, impl: Dict[str, Any]) -> List[str]:
method _check_assumptions_verified (line 146) | def _check_assumptions_verified(self, impl: Dict[str, Any]) -> List[str]:
method _check_evidence_exists (line 163) | def _check_evidence_exists(self, impl: Dict[str, Any]) -> List[str]:
method _detect_hallucinations (line 187) | def _detect_hallucinations(self, impl: Dict[str, Any]) -> List[str]:
method format_report (line 231) | def format_report(self, passed: bool, issues: List[str]) -> str:
FILE: src/superclaude/pm_agent/token_budget.py
class TokenBudgetManager (line 17) | class TokenBudgetManager:
method __init__ (line 33) | def __init__(self, complexity: ComplexityLevel = "medium"):
method allocate (line 48) | def allocate(self, amount: int) -> bool:
method use (line 63) | def use(self, amount: int) -> bool:
method remaining (line 72) | def remaining(self) -> int:
method remaining_tokens (line 76) | def remaining_tokens(self) -> int:
method reset (line 80) | def reset(self) -> None:
method __repr__ (line 84) | def __repr__(self) -> str:
FILE: src/superclaude/pytest_plugin.py
function pytest_configure (line 20) | def pytest_configure(config):
function confidence_checker (line 46) | def confidence_checker():
function self_check_protocol (line 59) | def self_check_protocol():
function reflexion_pattern (line 72) | def reflexion_pattern():
function token_budget (line 85) | def token_budget(request):
function pm_context (line 106) | def pm_context(tmp_path):
function pytest_runtest_setup (line 136) | def pytest_runtest_setup(item):
function pytest_runtest_makereport (line 160) | def pytest_runtest_makereport(item, call):
function pytest_report_header (line 187) | def pytest_report_header(config):
function pytest_collection_modifyitems (line 194) | def pytest_collection_modifyitems(config, items):
FILE: src/superclaude/scripts/clean_command_names.py
function find_project_root (line 23) | def find_project_root() -> Path:
function clean_name_attributes (line 45) | def clean_name_attributes(content: str) -> Tuple[str, bool]:
function process_commands_directory (line 75) | def process_commands_directory(commands_dir: Path) -> int:
function main (line 128) | def main() -> int:
FILE: src/superclaude/skills/confidence-check/confidence.ts
type Context (line 24) | interface Context {
class ConfidenceChecker (line 53) | class ConfidenceChecker {
method assess (line 67) | async assess(context: Context): Promise<number> {
method hasOfficialDocs (line 130) | private hasOfficialDocs(context: Context): boolean {
method noDuplicates (line 168) | private noDuplicates(context: Context): boolean {
method architectureCompliant (line 182) | private architectureCompliant(context: Context): boolean {
method hasOssReference (line 196) | private hasOssReference(context: Context): boolean {
method rootCauseIdentified (line 210) | private rootCauseIdentified(context: Context): boolean {
method hasExistingPatterns (line 222) | private hasExistingPatterns(context: Context): boolean {
method hasClearPath (line 253) | private hasClearPath(context: Context): boolean {
method getRecommendation (line 276) | getRecommendation(confidence: number): string {
function confidenceCheck (line 292) | async function confidenceCheck(context: Context): Promise<number> {
function getRecommendation (line 302) | function getRecommendation(confidence: number): string {
FILE: tests/conftest.py
function sample_context (line 12) | def sample_context():
function low_confidence_context (line 32) | def low_confidence_context():
function sample_implementation (line 52) | def sample_implementation():
function failing_implementation (line 76) | def failing_implementation():
function temp_memory_dir (line 97) | def temp_memory_dir(tmp_path):
FILE: tests/integration/test_pytest_plugin.py
class TestPytestPluginIntegration (line 10) | class TestPytestPluginIntegration:
method test_confidence_checker_fixture_available (line 13) | def test_confidence_checker_fixture_available(self, confidence_checker):
method test_self_check_protocol_fixture_available (line 19) | def test_self_check_protocol_fixture_available(self, self_check_protoc...
method test_reflexion_pattern_fixture_available (line 25) | def test_reflexion_pattern_fixture_available(self, reflexion_pattern):
method test_token_budget_fixture_available (line 31) | def test_token_budget_fixture_available(self, token_budget):
method test_pm_context_fixture_available (line 37) | def test_pm_context_fixture_available(self, pm_context):
method test_all_fixtures_work_together (line 45) | def test_all_fixtures_work_together(
method test_pytest_markers_registered (line 92) | def test_pytest_markers_registered(self):
class TestPytestPluginHooks (line 101) | class TestPytestPluginHooks:
method test_plugin_loaded (line 104) | def test_plugin_loaded(self):
method test_auto_markers_applied (line 110) | def test_auto_markers_applied(self, request):
function test_integration_marker_works (line 124) | def test_integration_marker_works():
function test_pm_context_memory_structure (line 133) | def test_pm_context_memory_structure(pm_context):
FILE: tests/unit/test_cli_install.py
class TestInstallCommands (line 14) | class TestInstallCommands:
method test_list_available_commands (line 17) | def test_list_available_commands(self):
method test_install_commands_to_temp_dir (line 26) | def test_install_commands_to_temp_dir(self, tmp_path):
method test_install_commands_skip_existing (line 44) | def test_install_commands_skip_existing(self, tmp_path):
method test_install_commands_force_reinstall (line 57) | def test_install_commands_force_reinstall(self, tmp_path):
method test_list_installed_commands (line 80) | def test_list_installed_commands(self, tmp_path):
method test_install_commands_creates_target_directory (line 97) | def test_install_commands_creates_target_directory(self, tmp_path):
method test_available_commands_format (line 108) | def test_available_commands_format(self):
method test_research_command_exists (line 121) | def test_research_command_exists(self, tmp_path):
method test_all_expected_commands_available (line 134) | def test_all_expected_commands_available(self):
class TestInstallCommandsEdgeCases (line 146) | class TestInstallCommandsEdgeCases:
method test_install_to_nonexistent_parent (line 149) | def test_install_to_nonexistent_parent(self, tmp_path):
method test_empty_target_directory_ok (line 158) | def test_empty_target_directory_ok(self, tmp_path):
function test_cli_integration (line 168) | def test_cli_integration():
FILE: tests/unit/test_confidence.py
class TestConfidenceChecker (line 12) | class TestConfidenceChecker:
method test_high_confidence_scenario (line 15) | def test_high_confidence_scenario(self, sample_context):
method test_low_confidence_scenario (line 33) | def test_low_confidence_scenario(self, low_confidence_context):
method test_medium_confidence_scenario (line 45) | def test_medium_confidence_scenario(self):
method test_confidence_checks_recorded (line 68) | def test_confidence_checks_recorded(self, sample_context):
method test_get_recommendation_high (line 81) | def test_get_recommendation_high(self):
method test_get_recommendation_medium (line 89) | def test_get_recommendation_medium(self):
method test_get_recommendation_low (line 97) | def test_get_recommendation_low(self):
method test_has_official_docs_with_flag (line 105) | def test_has_official_docs_with_flag(self):
method test_no_duplicates_check (line 114) | def test_no_duplicates_check(self):
method test_architecture_compliance_check (line 126) | def test_architecture_compliance_check(self):
method test_oss_reference_check (line 138) | def test_oss_reference_check(self):
method test_root_cause_check (line 150) | def test_root_cause_check(self):
function test_confidence_check_marker_integration (line 164) | def test_confidence_check_marker_integration(confidence_checker):
FILE: tests/unit/test_reflexion.py
class TestReflexionPattern (line 12) | class TestReflexionPattern:
method test_initialization (line 15) | def test_initialization(self):
method test_record_error_basic (line 23) | def test_record_error_basic(self):
method test_record_error_with_solution (line 37) | def test_record_error_with_solution(self):
method test_get_solution_for_known_error (line 50) | def test_get_solution_for_known_error(self):
method test_error_pattern_matching (line 71) | def test_error_pattern_matching(self):
method test_reflexion_memory_persistence (line 98) | def test_reflexion_memory_persistence(self, temp_memory_dir):
method test_error_learning_across_sessions (line 111) | def test_error_learning_across_sessions(self):
function test_reflexion_marker_integration (line 139) | def test_reflexion_marker_integration(reflexion_pattern):
function test_reflexion_with_real_exception (line 159) | def test_reflexion_with_real_exception():
FILE: tests/unit/test_self_check.py
class TestSelfCheckProtocol (line 12) | class TestSelfCheckProtocol:
method test_validate_passing_implementation (line 15) | def test_validate_passing_implementation(self, sample_implementation):
method test_validate_failing_implementation (line 31) | def test_validate_failing_implementation(self, failing_implementation):
method test_check_tests_passing_with_output (line 47) | def test_check_tests_passing_with_output(self):
method test_check_requirements_met (line 65) | def test_check_requirements_met(self):
method test_check_assumptions_verified (line 86) | def test_check_assumptions_verified(self):
method test_check_evidence_exists (line 107) | def test_check_evidence_exists(self):
method test_detect_hallucinations_tests_without_output (line 130) | def test_detect_hallucinations_tests_without_output(self):
method test_detect_hallucinations_complete_without_evidence (line 144) | def test_detect_hallucinations_complete_without_evidence(self):
method test_detect_hallucinations_complete_with_failing_tests (line 158) | def test_detect_hallucinations_complete_with_failing_tests(self):
method test_detect_hallucinations_ignored_errors (line 172) | def test_detect_hallucinations_ignored_errors(self):
method test_detect_hallucinations_uncertainty_language (line 187) | def test_detect_hallucinations_uncertainty_language(self):
method test_format_report_passing (line 200) | def test_format_report_passing(self):
method test_format_report_failing (line 209) | def test_format_report_failing(self):
function test_self_check_marker_integration (line 227) | def test_self_check_marker_integration(self_check_protocol, sample_imple...
FILE: tests/unit/test_token_budget.py
class TestTokenBudgetManager (line 12) | class TestTokenBudgetManager:
method test_simple_complexity (line 15) | def test_simple_complexity(self):
method test_medium_complexity (line 22) | def test_medium_complexity(self):
method test_complex_complexity (line 29) | def test_complex_complexity(self):
method test_default_complexity (line 36) | def test_default_complexity(self):
method test_invalid_complexity_defaults_to_medium (line 43) | def test_invalid_complexity_defaults_to_medium(self):
method test_token_usage_tracking (line 50) | def test_token_usage_tracking(self):
method test_budget_allocation_strategy (line 61) | def test_budget_allocation_strategy(self):
method test_complexity_examples (line 74) | def test_complexity_examples(self):
function test_complexity_marker_simple (line 90) | def test_complexity_marker_simple(token_budget):
function test_complexity_marker_medium (line 101) | def test_complexity_marker_medium(token_budget):
function test_complexity_marker_complex (line 112) | def test_complexity_marker_complex(token_budget):
function test_token_budget_no_marker (line 122) | def test_token_budget_no_marker(token_budget):
Condensed preview — 403 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (2,682K chars).
[
{
"path": ".claude/settings.json",
"chars": 3,
"preview": "{}\n"
},
{
"path": ".claude/skills/confidence-check/SKILL.md",
"chars": 3315,
"preview": "---\nname: Confidence Check\ndescription: Pre-implementation confidence assessment (≥90% required). Use before starting an"
},
{
"path": ".claude/skills/confidence-check/confidence.ts",
"chars": 5011,
"preview": "/**\n * Confidence Check - Pre-implementation confidence assessment\n *\n * Prevents wrong-direction execution by assessing"
},
{
"path": ".github/FUNDING.yml",
"chars": 799,
"preview": "# These are supported funding model platforms\n\ngithub: NomenAK\npatreon: # SuperClaude\nopen_collective: # Replace with a "
},
{
"path": ".github/PULL_REQUEST_TEMPLATE.md",
"chars": 921,
"preview": "# Pull Request\n\n## 概要\n\n<!-- このPRの目的を簡潔に説明 -->\n\n## 変更内容\n\n<!-- 主な変更点をリストアップ -->\n-\n\n## 関連Issue\n\n<!-- 関連するIssue番号があれば記載 -->\n"
},
{
"path": ".github/workflows/README.md",
"chars": 4896,
"preview": "# GitHub Actions Workflows\n\nThis directory contains CI/CD workflows for SuperClaude Framework.\n\n## Workflows\n\n### 1. **t"
},
{
"path": ".github/workflows/publish-pypi.yml",
"chars": 5707,
"preview": "name: Publish to PyPI\n\non:\n # Trigger on new releases\n release:\n types: [published]\n \n # Allow manual triggering\n"
},
{
"path": ".github/workflows/pull-sync-framework.yml",
"chars": 5341,
"preview": "name: Pull Sync from Framework\n\non:\n schedule:\n - cron: '0 */6 * * *'\n workflow_dispatch:\n\njobs:\n sync-and-isolate"
},
{
"path": ".github/workflows/quick-check.yml",
"chars": 1240,
"preview": "name: Quick Check\n\non:\n pull_request:\n branches: [master, integration]\n\njobs:\n quick-test:\n name: Quick Test (Py"
},
{
"path": ".github/workflows/readme-quality-check.yml",
"chars": 13040,
"preview": "name: README Quality Check\n\non:\n pull_request:\n paths: \n - 'README*.md'\n - 'Docs/**/*.md'\n push:\n bran"
},
{
"path": ".github/workflows/test.yml",
"chars": 4602,
"preview": "name: Tests\n\non:\n push:\n branches: [master, integration]\n pull_request:\n branches: [master, integration]\n workf"
},
{
"path": ".gitignore",
"chars": 2148,
"preview": "# Python\n__pycache__/\n*.py[cod]\n*$py.class\n*.so\n.Python\nbuild/\ndevelop-eggs/\ndist/\ndownloads/\neggs/\n.eggs/\nlib/\nlib64/\np"
},
{
"path": ".pre-commit-config.yaml",
"chars": 2879,
"preview": "# SuperClaude Framework - Pre-commit Hooks\n# See https://pre-commit.com for more information\n\nrepos:\n # Basic file chec"
},
{
"path": "AGENTS.md",
"chars": 2860,
"preview": "# Repository Guidelines\n\n## Project Structure & Module Organization\n- `src/superclaude/` holds the Python package and py"
},
{
"path": "CHANGELOG.md",
"chars": 10292,
"preview": "# Changelog\n\nAll notable changes to SuperClaude will be documented in this file.\n\nThe format is based on [Keep a Changel"
},
{
"path": "CLAUDE.md",
"chars": 9382,
"preview": "# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## "
},
{
"path": "CODEOWNERS",
"chars": 21,
"preview": "* @NomenAK @mithun50\n"
},
{
"path": "CODE_OF_CONDUCT.md",
"chars": 28139,
"preview": "# Code of Conduct\n\n## 🤝 Our Commitment\n\nSuperClaude Framework is committed to fostering an inclusive, professional, and "
},
{
"path": "CONTRIBUTING.md",
"chars": 17620,
"preview": "# Contributing to SuperClaude Framework\n\nSuperClaude Framework transforms Claude Code into a structured development plat"
},
{
"path": "DELETION_RATIONALE.md",
"chars": 10539,
"preview": "# Deletion Rationale (Evidence-Based)\n\n**PR Target Branch**: `next`\n**Base Branch**: `master`\n**Date**: 2025-10-24\n\n---\n"
},
{
"path": "KNOWLEDGE.md",
"chars": 14561,
"preview": "# KNOWLEDGE.md\n\n**Accumulated Insights, Best Practices, and Troubleshooting for SuperClaude Framework**\n\n> This document"
},
{
"path": "LICENSE",
"chars": 1090,
"preview": "MIT License\n\nCopyright (c) 2024 SuperClaude Framework Contributors\n\nPermission is hereby granted, free of charge, to any"
},
{
"path": "MANIFEST.in",
"chars": 1388,
"preview": "include VERSION\ninclude README.md\ninclude LICENSE\ninclude CHANGELOG.md\ninclude CONTRIBUTING.md\ninclude SECURITY.md\ninclu"
},
{
"path": "Makefile",
"chars": 5203,
"preview": ".PHONY: install test test-plugin doctor verify clean lint format build-plugin sync-plugin-repo uninstall-legacy help\n\n# "
},
{
"path": "PARALLEL_INDEXING_PLAN.md",
"chars": 4475,
"preview": "# Parallel Repository Indexing Execution Plan\n\n## Objective\nCreate comprehensive repository index for: /Users/kazuki/git"
},
{
"path": "PLANNING.md",
"chars": 11620,
"preview": "# PLANNING.md\n\n**Architecture, Design Principles, and Absolute Rules for SuperClaude Framework**\n\n> This document is rea"
},
{
"path": "PLUGIN_INSTALL.md",
"chars": 2495,
"preview": "# SuperClaude Plugin Installation Guide\n\n## 公式インストール方法（推奨）\n\n### 前提条件\n\n1. **ripgrep のインストール**\n ```bash\n brew install "
},
{
"path": "PROJECT_INDEX.json",
"chars": 7255,
"preview": "{\n \"metadata\": {\n \"generated_at\": \"2025-10-29T00:00:00Z\",\n \"version\": \"0.4.0\",\n \"total_files\": 196,\n \"pytho"
},
{
"path": "PROJECT_INDEX.md",
"chars": 9733,
"preview": "# Project Index: SuperClaude Framework\n\n**Generated**: 2025-10-29\n**Version**: 0.4.0\n**Description**: AI-enhanced develo"
},
{
"path": "PR_DOCUMENTATION.md",
"chars": 7738,
"preview": "# PR: PM Mode as Default - Phase 1 Implementation\n\n**Status**: ✅ Ready for Review\n**Test Coverage**: 26 tests, all passi"
},
{
"path": "QUALITY_COMPARISON.md",
"chars": 6608,
"preview": "# Quality Comparison: Python vs TypeScript Implementation\n\n**Date**: 2025-10-21\n**Status**: ✅ **TypeScript version match"
},
{
"path": "README-ja.md",
"chars": 12363,
"preview": "<div align=\"center\">\n\n# 🚀 SuperClaudeフレームワーク\n\n### **Claude Codeを構造化開発プラットフォームに変換**\n\n<p align=\"center\">\n <img src=\"https"
},
{
"path": "README-kr.md",
"chars": 12347,
"preview": "<div align=\"center\">\n\n# 🚀 SuperClaude 프레임워크\n\n### **Claude Code를 구조화된 개발 플랫폼으로 변환**\n\n<p align=\"center\">\n <img src=\"https"
},
{
"path": "README-zh.md",
"chars": 10892,
"preview": "<div align=\"center\">\n\n# 🚀 SuperClaude 框架\n\n### **将Claude Code转换为结构化开发平台**\n\n<p align=\"center\">\n <img src=\"https://img.shi"
},
{
"path": "README.md",
"chars": 19229,
"preview": "<div align=\"center\">\n\n# 🚀 SuperClaude Framework\n\n[]("
},
{
"path": "SECURITY.md",
"chars": 33041,
"preview": "# Security Policy\n\n## 🔒 Reporting Security Vulnerabilities\n\nSuperClaude Framework prioritizes security through secure-by"
},
{
"path": "TASK.md",
"chars": 9645,
"preview": "# TASK.md\n\n**Current Tasks, Priorities, and Backlog for SuperClaude Framework**\n\n> This document tracks active developme"
},
{
"path": "TEST_PLUGIN.md",
"chars": 1259,
"preview": "# PM Agent Plugin Performance Test\n\n## Test Commands (Run in New Session)\n\n```bash\n/plugin marketplace add superclaude-l"
},
{
"path": "VERSION",
"chars": 6,
"preview": "4.2.0\n"
},
{
"path": "docs/Development/ARCHITECTURE.md",
"chars": 13699,
"preview": "# SuperClaude Architecture\n\n**Last Updated**: 2025-10-14\n**Version**: 4.1.5\n\n## 📋 Table of Contents\n\n1. [System Overview"
},
{
"path": "docs/Development/PROJECT_STATUS.md",
"chars": 4273,
"preview": "# SuperClaude Project Status\n\n**Last Updated**: 2025-10-14\n**Version**: 4.1.5\n**Phase**: Phase 1 - Documentation Structu"
},
{
"path": "docs/Development/ROADMAP.md",
"chars": 11020,
"preview": "# SuperClaude Development Roadmap\n\n**Last Updated**: 2025-10-14\n**Version**: 4.1.5\n\n## 🎯 Vision\n\nTransform SuperClaude i"
},
{
"path": "docs/Development/TASKS.md",
"chars": 3743,
"preview": "# SuperClaude Development Tasks\n\n**Last Updated**: 2025-10-14\n**Current Sprint**: Phase 1 - Documentation Structure\n\n---"
},
{
"path": "docs/Development/hypothesis-pm-autonomous-enhancement-2025-10-14.md",
"chars": 7384,
"preview": "# PM Agent Autonomous Enhancement - 改善提案\n\n> **Date**: 2025-10-14\n> **Status**: 提案中（ユーザーレビュー待ち）\n> **Goal**: ユーザーインプット最小化 "
},
{
"path": "docs/Development/installation-flow-understanding.md",
"chars": 6673,
"preview": "# SuperClaude Installation Flow - Complete Understanding\n\n> **学習内容**: インストーラーがどうやって `~/.claude/` にファイルを配置するかの完全理解\n\n---\n\n"
},
{
"path": "docs/Development/pm-agent-ideal-workflow.md",
"chars": 5581,
"preview": "# PM Agent - Ideal Autonomous Workflow\n\n> **目的**: 何百回も同じ指示を繰り返さないための自律的オーケストレーションシステム\n\n## 🎯 解決すべき問題\n\n### 現状の課題\n- **繰り返し指"
},
{
"path": "docs/Development/pm-agent-integration.md",
"chars": 10936,
"preview": "# PM Agent Mode Integration Guide\n\n**Last Updated**: 2025-10-14\n**Target Version**: 4.2.0\n**Status**: Implementation Gui"
},
{
"path": "docs/Development/project-structure-understanding.md",
"chars": 6124,
"preview": "# SuperClaude Framework - Project Structure Understanding\n\n> **Critical Understanding**: このプロジェクトとインストール後の環境の関係\n\n---\n\n##"
},
{
"path": "docs/Development/tasks/current-tasks.md",
"chars": 3191,
"preview": "# Current Tasks - SuperClaude Framework\n\n> **Last Updated**: 2025-10-14\n> **Session**: PM Agent Enhancement & PDCA Integ"
},
{
"path": "docs/PR_STRATEGY.md",
"chars": 7709,
"preview": "# PR Strategy for Clean Architecture Migration\n\n**Date**: 2025-10-21\n**Target**: SuperClaude-Org/SuperClaude_Framework\n*"
},
{
"path": "docs/README.md",
"chars": 5474,
"preview": "# SuperClaude Documentation\n\n## 🎯 Essential Understanding\n\n**SuperClaude is a Context Framework for Claude Code** - it i"
},
{
"path": "docs/Templates/__init__.py",
"chars": 0,
"preview": ""
},
{
"path": "docs/agents/pm-agent-guide.md",
"chars": 9052,
"preview": "# PM Agent Guide\n\nDetailed philosophy, examples, and quality standards for the PM Agent.\n\n**For execution workflows**, s"
},
{
"path": "docs/architecture/CONTEXT_WINDOW_ANALYSIS.md",
"chars": 7640,
"preview": "# Context Window Analysis: Old vs New Architecture\n\n**Date**: 2025-10-21\n**Related Issue**: [#437 - Extreme Context Wind"
},
{
"path": "docs/architecture/MIGRATION_TO_CLEAN_ARCHITECTURE.md",
"chars": 18467,
"preview": "# Migration to Clean Plugin Architecture\n\n**Date**: 2025-10-21\n**Status**: Planning → Implementation\n**Goal**: Zero-foot"
},
{
"path": "docs/architecture/PHASE_1_COMPLETE.md",
"chars": 7678,
"preview": "# Phase 1 Migration Complete ✅\n\n**Date**: 2025-10-21\n**Status**: SUCCESSFULLY COMPLETED\n**Architecture**: Zero-Footprint"
},
{
"path": "docs/architecture/PHASE_2_COMPLETE.md",
"chars": 7111,
"preview": "# Phase 2 Migration Complete ✅\n\n**Date**: 2025-10-21\n**Status**: SUCCESSFULLY COMPLETED\n**Focus**: Test Migration & Plug"
},
{
"path": "docs/architecture/PHASE_3_COMPLETE.md",
"chars": 12954,
"preview": "# Phase 3 Migration Complete ✅\n\n**Date**: 2025-10-21\n**Status**: SUCCESSFULLY COMPLETED\n**Focus**: Clean Installation Ve"
},
{
"path": "docs/architecture/PM_AGENT_COMPARISON.md",
"chars": 10425,
"preview": "# PM Agent: Upstream vs Clean Architecture Comparison\n\n**Date**: 2025-10-21\n**Purpose**: 本家（Upstream）と今回のクリーンアーキテクチャでのPM"
},
{
"path": "docs/architecture/SKILLS_CLEANUP.md",
"chars": 3677,
"preview": "# Skills Cleanup for Clean Architecture\n\n**Date**: 2025-10-21\n**Issue**: `~/.claude/skills/` に古いSkillsが残っている\n**Impact**:"
},
{
"path": "docs/architecture/pm-agent-auto-activation.md",
"chars": 12425,
"preview": "# PM Agent Auto-Activation Architecture\n\n## Problem Statement\n\n**Current Issue**: PM Agent functionality requires manual"
},
{
"path": "docs/architecture/pm-agent-responsibility-cleanup.md",
"chars": 5785,
"preview": "# PM Agent Responsibility Cleanup & MCP Integration\n\n## 問題整理\n\n### 1. 既存MODEとの重複\n\n**MODE_Task_Management.md と pm-agent.md"
},
{
"path": "docs/capability-mapping-v5.md",
"chars": 9227,
"preview": "# SuperClaude v5: Capability-Driven Architecture\n\n## Executive Summary\n\nSuperClaude v4.x has 30 commands that create cog"
},
{
"path": "docs/developer-guide/README.md",
"chars": 8317,
"preview": "# SuperClaude Framework Developer Guide\n\nA documentation suite for understanding and extending the SuperClaude Context-O"
},
{
"path": "docs/developer-guide/contributing-code.md",
"chars": 11954,
"preview": "# Contributing Context Files to SuperClaude Framework 🛠️\n\nWelcome to SuperClaude Framework development! This guide provi"
},
{
"path": "docs/developer-guide/documentation-index.md",
"chars": 11963,
"preview": "# SuperClaude Framework developer-guide Index\n\n## Document Navigation Guide\n\nThis index provides comprehensive access to"
},
{
"path": "docs/developer-guide/technical-architecture.md",
"chars": 12595,
"preview": "# SuperClaude Context Architecture Guide\n\n## Overview\n\nThis guide documents how SuperClaude's Context-Oriented Configura"
},
{
"path": "docs/developer-guide/testing-debugging.md",
"chars": 8094,
"preview": "# SuperClaude Verification and Troubleshooting Guide\n\n## Overview\n\nThis guide covers how to verify your SuperClaude inst"
},
{
"path": "docs/getting-started/installation.md",
"chars": 10071,
"preview": "<div align=\"center\">\n\n# 📦 SuperClaude Installation Guide\n\n### **Transform Claude Code with 21 Commands, 14 Agents & 6 MC"
},
{
"path": "docs/getting-started/quick-start.md",
"chars": 10052,
"preview": "<div align=\"center\">\n\n# 🚀 SuperClaude Quick Start Guide\n\n### **Context Engineering Framework for Claude Code**\n\n<p align"
},
{
"path": "docs/mcp/mcp-integration-policy.md",
"chars": 11824,
"preview": "# MCP Integration Policy\n\nIntegration policy and usage guidelines for MCP (Model Context Protocol) servers in SuperClaud"
},
{
"path": "docs/mcp/mcp-optional-design.md",
"chars": 9635,
"preview": "# MCP Optional Design\n\n## 基本原則: MCPはオプション\n\n**重要**: SuperClaude Frameworkは **MCPなしでも完全に動作** します。\n\n```yaml\nCore Principle:"
},
{
"path": "docs/memory/README.md",
"chars": 7274,
"preview": "# Memory Directory\n\nThis directory contains memory and learning data for the SuperClaude Framework's PM Agent.\n\n## Overv"
},
{
"path": "docs/memory/WORKFLOW_METRICS_SCHEMA.md",
"chars": 10489,
"preview": "# Workflow Metrics Schema\n\n**Purpose**: Token efficiency tracking for continuous optimization and A/B testing\n\n**File**:"
},
{
"path": "docs/memory/last_session.md",
"chars": 6096,
"preview": "# Last Session Summary\n\n**Date**: 2025-10-17\n**Duration**: ~2.5 hours\n**Goal**: テストスイート実装 + メトリクス収集システム構築\n\n---\n\n## ✅ Wha"
},
{
"path": "docs/memory/next_actions.md",
"chars": 5602,
"preview": "# Next Actions\n\n**Updated**: 2025-10-17\n**Priority**: Testing & Validation → Metrics Collection\n\n---\n\n## 🎯 Immediate Act"
},
{
"path": "docs/memory/patterns_learned.jsonl",
"chars": 132,
"preview": "{\"pattern\":\"local-file-memory\",\"description\":\"PM Agent uses local files in docs/memory/ instead of Serena MCP\",\"date\":\"2"
},
{
"path": "docs/memory/pm_context.md",
"chars": 3978,
"preview": "# PM Agent Context\n\n**Project**: SuperClaude_Framework\n**Type**: AI Agent Framework\n**Tech Stack**: Claude Code, MCP Ser"
},
{
"path": "docs/memory/reflexion.jsonl.example",
"chars": 7312,
"preview": "{\"ts\": \"2025-10-17T09:23:15+09:00\", \"task\": \"implement JWT authentication\", \"mistake\": \"JWT validation failed with undef"
},
{
"path": "docs/memory/solutions_learned.jsonl",
"chars": 10843,
"preview": "{\"test_name\": \"test_feature\", \"error_type\": \"AssertionError\", \"error_message\": \"Expected 5, got 3\", \"traceback\": \"File t"
},
{
"path": "docs/memory/token_efficiency_validation.md",
"chars": 6622,
"preview": "# Token Efficiency Validation Report\n\n**Date**: 2025-10-17\n**Purpose**: Validate PM Agent token-efficient architecture i"
},
{
"path": "docs/memory/workflow_metrics.jsonl",
"chars": 443,
"preview": "{\n \"timestamp\": \"2025-10-17T03:15:00+09:00\",\n \"session_id\": \"test_initialization\",\n \"task_type\": \"schema_creation\",\n "
},
{
"path": "docs/mistakes/test_database_connection-2025-11-11.md",
"chars": 417,
"preview": "# Mistake Record: test_database_connection\n\n**Date**: 2025-11-11\n**Error Type**: ConnectionError\n\n---\n\n## ❌ What Happene"
},
{
"path": "docs/mistakes/test_database_connection-2025-11-14.md",
"chars": 417,
"preview": "# Mistake Record: test_database_connection\n\n**Date**: 2025-11-14\n**Error Type**: ConnectionError\n\n---\n\n## ❌ What Happene"
},
{
"path": "docs/mistakes/test_reflexion_with_real_exception-2025-11-11.md",
"chars": 414,
"preview": "# Mistake Record: test_reflexion_with_real_exception\n\n**Date**: 2025-11-11\n**Error Type**: ZeroDivisionError\n\n---\n\n## ❌ "
},
{
"path": "docs/mistakes/test_reflexion_with_real_exception-2025-11-14.md",
"chars": 414,
"preview": "# Mistake Record: test_reflexion_with_real_exception\n\n**Date**: 2025-11-14\n**Error Type**: ZeroDivisionError\n\n---\n\n## ❌ "
},
{
"path": "docs/mistakes/unknown-2025-11-11.md",
"chars": 374,
"preview": "# Mistake Record: unknown\n\n**Date**: 2025-11-11\n**Error Type**: FileNotFoundError\n\n---\n\n## ❌ What Happened\n\nconfig.json "
},
{
"path": "docs/mistakes/unknown-2025-11-14.md",
"chars": 374,
"preview": "# Mistake Record: unknown\n\n**Date**: 2025-11-14\n**Error Type**: FileNotFoundError\n\n---\n\n## ❌ What Happened\n\nconfig.json "
},
{
"path": "docs/next-refactor-plan.md",
"chars": 5456,
"preview": "# Next Refactor Direction Overview\n\n## 1. Slash Command Audit (upstream/master)\n\n| Command | Primary Purpose | Claude Co"
},
{
"path": "docs/plugin-reorg.md",
"chars": 2660,
"preview": "# SuperClaude Plugin Re-organization Plan\n\n## Source of Truth\n\n| Area | Current Repo | Target Location (Framework) | Not"
},
{
"path": "docs/pm-agent-implementation-status.md",
"chars": 9942,
"preview": "# PM Agent Implementation Status\n\n**Last Updated**: 2025-10-14\n**Version**: 1.0.0\n\n## 📋 Overview\n\nPM Agent has been rede"
},
{
"path": "docs/reference/README.md",
"chars": 10978,
"preview": "# SuperClaude Framework Reference Documentation\n\n**Navigation Hub**: Structured learning paths and technical references "
},
{
"path": "docs/reference/advanced-patterns.md",
"chars": 8675,
"preview": "# SuperClaude Advanced Patterns\n\n**Advanced Context Usage Patterns**: Sophisticated combinations of commands, agents, an"
},
{
"path": "docs/reference/advanced-workflows.md",
"chars": 8111,
"preview": "# SuperClaude Advanced Workflows Collection\n\n**Status**: ✅ **Status: Current** - Complex command sequences and context c"
},
{
"path": "docs/reference/basic-examples.md",
"chars": 17241,
"preview": "# SuperClaude Basic Examples Collection\n\n**Status**: ✅ **Status: Current** - Essential commands, single-agent workflows,"
},
{
"path": "docs/reference/claude-code-history-management.md",
"chars": 16800,
"preview": "# Claude Code Conversation History Management Research\n\n**Research Date**: 2025-10-09\n**Purpose**: Understand .jsonl fil"
},
{
"path": "docs/reference/commands-list.md",
"chars": 2392,
"preview": "# SuperClaude Commands Reference\n\nComplete list of all 30 slash commands available in SuperClaude Framework v4.1.9+\n\n## "
},
{
"path": "docs/reference/common-issues.md",
"chars": 1781,
"preview": "# SuperClaude Common Issues - Quick Reference 🚀\n\n**Problem Solving Guide**: Most frequent issues with practical solution"
},
{
"path": "docs/reference/comprehensive-features.md",
"chars": 5983,
"preview": "# SuperClaude Framework - Comprehensive Feature List\n\nComplete inventory of all features restored in v4.1.9+\n\n## 📋 Comma"
},
{
"path": "docs/reference/diagnostic-reference.md",
"chars": 8691,
"preview": "# SuperClaude Diagnostic Reference Guide\n\n## Overview\n\nThis guide provides procedures for diagnosing issues with SuperCl"
},
{
"path": "docs/reference/examples-cookbook.md",
"chars": 9029,
"preview": "# SuperClaude Examples Cookbook\n\n**Status**: ✅ **Status: Current** - Comprehensive collection of practical SuperClaude u"
},
{
"path": "docs/reference/integration-patterns.md",
"chars": 8355,
"preview": "# SuperClaude Integration Patterns Collection\n\n**Status**: ✅ **Status: Current** - Context patterns for framework integr"
},
{
"path": "docs/reference/mcp-server-guide.md",
"chars": 20544,
"preview": "# MCP Server Troubleshooting Guide\n\n**MCP Server Focus**: Model Context Protocol (MCP) servers provide enhanced capabili"
},
{
"path": "docs/reference/pm-agent-autonomous-reflection.md",
"chars": 16600,
"preview": "# PM Agent: Autonomous Reflection & Token Optimization\n\n**Version**: 2.0\n**Date**: 2025-10-17\n**Status**: Production Rea"
},
{
"path": "docs/reference/suggested-commands.md",
"chars": 2065,
"preview": "# 推奨コマンド集\n\n## インストール・セットアップ\n```bash\n# 推奨インストール方法\npipx install SuperClaude\npipx upgrade SuperClaude\nSuperClaude install\n\n"
},
{
"path": "docs/reference/troubleshooting.md",
"chars": 2960,
"preview": "# SuperClaude Troubleshooting Guide 🔧\n\nQuick fixes to advanced diagnostics for SuperClaude Framework issues.\n\n## Quick F"
},
{
"path": "docs/research/complete-python-skills-migration.md",
"chars": 26910,
"preview": "# Complete Python + Skills Migration Plan\n\n**Date**: 2025-10-20\n**Goal**: 全部Python化 + Skills API移行で98%トークン削減\n**Timeline*"
},
{
"path": "docs/research/intelligent-execution-architecture.md",
"chars": 13931,
"preview": "# Intelligent Execution Architecture\n\n**Date**: 2025-10-21\n**Version**: 1.0.0\n**Status**: ✅ IMPLEMENTED\n\n## Executive Su"
},
{
"path": "docs/research/llm-agent-token-efficiency-2025.md",
"chars": 10721,
"preview": "# LLM Agent Token Efficiency & Context Management - 2025 Best Practices\n\n**Research Date**: 2025-10-17\n**Researcher**: P"
},
{
"path": "docs/research/markdown-to-python-migration-plan.md",
"chars": 11073,
"preview": "# Markdown → Python Migration Plan\n\n**Date**: 2025-10-20\n**Problem**: Markdown modes consume 41,000 tokens every session"
},
{
"path": "docs/research/mcp-installer-fix-summary.md",
"chars": 4261,
"preview": "# MCP Installer Fix Summary\n\n## Problem Identified\nThe SuperClaude Framework installer was using `claude mcp add` CLI co"
},
{
"path": "docs/research/parallel-execution-complete-findings.md",
"chars": 18015,
"preview": "# Complete Parallel Execution Findings - Final Report\n\n**Date**: 2025-10-20\n**Conversation**: PM Mode Quality Validation"
},
{
"path": "docs/research/parallel-execution-findings.md",
"chars": 7256,
"preview": "# Parallel Execution Findings & Implementation\n\n**Date**: 2025-10-20\n**Purpose**: 並列実行の実装と実測結果\n**Status**: ✅ 実装完了、⚠️ パフォ"
},
{
"path": "docs/research/phase1-implementation-strategy.md",
"chars": 9980,
"preview": "# Phase 1 Implementation Strategy\n\n**Date**: 2025-10-20\n**Status**: Strategic Decision Point\n\n## Context\n\nAfter implemen"
},
{
"path": "docs/research/pm-mode-performance-analysis.md",
"chars": 9113,
"preview": "# PM Mode Performance Analysis\n\n**Date**: 2025-10-19\n**Test Suite**: `tests/performance/test_pm_mode_performance.py`\n**S"
},
{
"path": "docs/research/pm-mode-validation-methodology.md",
"chars": 6930,
"preview": "# PM Mode Validation Methodology\n\n**Date**: 2025-10-19\n**Purpose**: Evidence-based validation of PM mode performance cla"
},
{
"path": "docs/research/pm-skills-migration-results.md",
"chars": 6255,
"preview": "# PM Agent Skills Migration - Results\n\n**Date**: 2025-10-21\n**Status**: ✅ SUCCESS\n**Migration Time**: ~30 minutes\n\n## Ex"
},
{
"path": "docs/research/pm_agent_roi_analysis_2025-10-21.md",
"chars": 8375,
"preview": "# PM Agent ROI Analysis: Self-Improving Agents with Latest Models (2025)\n\n**Date**: 2025-10-21\n**Research Question**: Sh"
},
{
"path": "docs/research/python_src_layout_research_20251021.md",
"chars": 4727,
"preview": "# Python Src Layout Research - Repository vs Package Naming\n\n**Date**: 2025-10-21\n**Question**: Should `superclaude` rep"
},
{
"path": "docs/research/reflexion-integration-2025.md",
"chars": 7144,
"preview": "# Reflexion Framework Integration - PM Agent\n\n**Date**: 2025-10-17\n**Purpose**: Integrate Reflexion self-reflection mech"
},
{
"path": "docs/research/repository-understanding-proposal.md",
"chars": 10204,
"preview": "# Repository Understanding & Auto-Indexing Proposal\n\n**Date**: 2025-10-19\n**Purpose**: Measure SuperClaude effectiveness"
},
{
"path": "docs/research/research_git_branch_integration_2025.md",
"chars": 8248,
"preview": "# Git Branch Integration Research: Master/Dev Divergence Resolution (2025)\n\n**Research Date**: 2025-10-16\n**Query**: Git"
},
{
"path": "docs/research/research_installer_improvements_20251017.md",
"chars": 28507,
"preview": "# SuperClaude Installer Improvement Recommendations\n\n**Research Date**: 2025-10-17\n**Query**: Python CLI installer best "
},
{
"path": "docs/research/research_oss_fork_workflow_2025.md",
"chars": 9845,
"preview": "# OSS Fork Workflow Best Practices 2025\n\n**Research Date**: 2025-10-16\n**Context**: 2-tier fork structure (OSS upstream "
},
{
"path": "docs/research/research_python_directory_naming_20251015.md",
"chars": 12054,
"preview": "# Python Documentation Directory Naming Convention Research\n\n**Date**: 2025-10-15\n**Research Question**: What is the cor"
},
{
"path": "docs/research/research_python_directory_naming_automation_2025.md",
"chars": 23250,
"preview": "# Research: Python Directory Naming & Automation Tools (2025)\n\n**Research Date**: 2025-10-14\n**Research Context**: PEP 8"
},
{
"path": "docs/research/research_repository_scoped_memory_2025-10-16.md",
"chars": 17250,
"preview": "# Repository-Scoped Memory Management for AI Coding Assistants\n**Research Report | 2025-10-16**\n\n## Executive Summary\n\nT"
},
{
"path": "docs/research/research_serena_mcp_2025-01-16.md",
"chars": 12846,
"preview": "# Serena MCP Research Report\n**Date**: 2025-01-16\n**Research Depth**: Deep\n**Confidence Level**: High (90%)\n\n## Executiv"
},
{
"path": "docs/research/skills-migration-test.md",
"chars": 2963,
"preview": "# Skills Migration Test - PM Agent\n\n**Date**: 2025-10-21\n**Goal**: Verify zero-footprint Skills migration works\n\n## Test"
},
{
"path": "docs/research/task-tool-parallel-execution-results.md",
"chars": 11646,
"preview": "# Task Tool Parallel Execution - Results & Analysis\n\n**Date**: 2025-10-20\n**Purpose**: Compare Threading vs Task Tool pa"
},
{
"path": "docs/sessions/2025-10-14-summary.md",
"chars": 1275,
"preview": "# Session Summary - PM Agent Enhancement (2025-10-14)\n\n## 完了したこと\n\n### 1. PM Agent理想ワークフローの明確化\n- File: `docs/development/"
},
{
"path": "docs/testing/pm-workflow-test-results.md",
"chars": 2442,
"preview": "# PM Agent Workflow Test Results - 2025-10-14\n\n## Test Objective\nVerify autonomous workflow execution and session restor"
},
{
"path": "docs/testing/procedures.md",
"chars": 1749,
"preview": "# テスト手順とCI/CD\n\n## テスト構成\n\n### pytest設定\n- **テストディレクトリ**: `tests/`\n- **テストファイルパターン**: `test_*.py`, `*_test.py`\n- **テストクラス**"
},
{
"path": "docs/troubleshooting/serena-installation.md",
"chars": 3351,
"preview": "# Serena MCP Installation Troubleshooting\n\n## Common Issues and Solutions\n\n### Issue: \"Failed to spawn: serena\" Error\n\n*"
},
{
"path": "docs/user-guide/agents.md",
"chars": 44881,
"preview": "# SuperClaude Agents Guide 🤖\n\nSuperClaude provides 16 domain specialist agents that Claude Code can invoke for specializ"
},
{
"path": "docs/user-guide/commands.md",
"chars": 50820,
"preview": "# SC Commands Reference\n\n**Complete SuperClaude Framework Command Reference**\n\n> This file serves two purposes: quick na"
},
{
"path": "docs/user-guide/flags.md",
"chars": 11346,
"preview": "# SuperClaude Flags Guide 🏁\n\n**Most flags activate automatically** - Claude Code reads behavioral instructions to engage"
},
{
"path": "docs/user-guide/mcp-installation.md",
"chars": 5833,
"preview": "# MCP Server Installation Guide\n\nSuperClaude provides a convenient CLI command for installing and managing MCP (Model Co"
},
{
"path": "docs/user-guide/mcp-servers.md",
"chars": 11939,
"preview": "# SuperClaude MCP Servers Guide 🔌\n\n## Overview\n\nMCP (Model Context Protocol) servers extend Claude Code's capabilities t"
},
{
"path": "docs/user-guide/memory-system.md",
"chars": 8330,
"preview": "# Memory System Guide\n\nSuperClaude Framework includes a built-in memory system called **ReflexionMemory** that helps the"
},
{
"path": "docs/user-guide/modes.md",
"chars": 27968,
"preview": "# SuperClaude Behavioral Modes Guide 🧠\n\n## ✅ Quick Verification\nTest modes by using `/sc:` commands - they activate auto"
},
{
"path": "docs/user-guide/session-management.md",
"chars": 10940,
"preview": "# Session Management Guide\n\nSuperClaude provides persistent session management through the Serena MCP server, enabling t"
},
{
"path": "docs/user-guide-jp/agents.md",
"chars": 33054,
"preview": "# SuperClaude エージェントガイド 🤖\n\n[](https://github.com/khayashi4337/SuperClaude_Framework/blob/master/docs/user-guide/agents.m"
},
{
"path": "docs/user-guide-jp/commands.md",
"chars": 14280,
"preview": "# SuperClaude コマンドガイド\n\n[](https://github.com/khayashi4337/SuperClaude_Framework/blob/master/docs/user-guide/commands.md#"
},
{
"path": "docs/user-guide-jp/flags.md",
"chars": 12849,
"preview": "# SuperClaude フラグガイド 🏁\n\n[](https://github.com/khayashi4337/SuperClaude_Framework/blob/master/docs/user-guide/flags.md#su"
},
{
"path": "docs/user-guide-jp/mcp-servers.md",
"chars": 8989,
"preview": "# SuperClaude MCP サーバーガイド 🔌\n\n[](https://github.com/khayashi4337/SuperClaude_Framework/blob/master/docs/user-guide/mcp-se"
},
{
"path": "docs/user-guide-jp/modes.md",
"chars": 23323,
"preview": "# SuperClaude 行動モードガイド 🧠\n\n[](https://github.com/khayashi4337/SuperClaude_Framework/blob/master/docs/user-guide/modes.md#"
},
{
"path": "docs/user-guide-jp/session-management.md",
"chars": 11706,
"preview": "# セッション管理ガイド\n\n[](https://github.com/khayashi4337/SuperClaude_Framework/blob/master/docs/user-guide/session-management.md"
},
{
"path": "docs/user-guide-kr/agents.md",
"chars": 25613,
"preview": "# SuperClaude 에이전트 가이드 🤖\n\nSuperClaude는 Claude Code가 전문 지식을 위해 호출할 수 있는 15개의 도메인 전문 에이전트를 제공합니다.\n\n## 🧪 에이전트 활성화 테스트\n\n이 가이"
},
{
"path": "docs/user-guide-kr/commands.md",
"chars": 10951,
"preview": "# SuperClaude 명령어 가이드\n\nSuperClaude는 Claude Code를 위한 25개의 명령어를 제공합니다: 워크플로우를 위한 `/sc:*` 명령어와 전문가를 위한 `@agent-*`.\n\n## 명령어 "
},
{
"path": "docs/user-guide-kr/flags.md",
"chars": 8202,
"preview": "# SuperClaude 플래그 가이드 🏁\n\n**대부분의 플래그는 자동으로 활성화됩니다** - Claude Code가 요청의 키워드와 패턴을 기반으로 적절한 컨텍스트를 참여시키는 행동 지침을 읽습니다.\n\n## 필수 "
},
{
"path": "docs/user-guide-kr/mcp-servers.md",
"chars": 7682,
"preview": "# SuperClaude MCP 서버 가이드 🔌\n\n## 개요\n\nMCP (Model Context Protocol) 서버는 전문 도구를 통해 Claude Code의 기능을 확장합니다. SuperClaude는 8개의 M"
},
{
"path": "docs/user-guide-kr/modes.md",
"chars": 15658,
"preview": "# SuperClaude 행동 모드 가이드 🧠\n\n## ✅ 빠른 확인\n`/sc:` 명령어를 사용하여 모드를 테스트하세요 - 작업 복잡성에 따라 자동으로 활성화됩니다. 전체 명령어 참조는 [명령어 가이드](command"
},
{
"path": "docs/user-guide-kr/session-management.md",
"chars": 5868,
"preview": "# 세션 관리 가이드\n\nSuperClaude는 Serena MCP 서버를 통해 영구 세션 관리를 제공하여 Claude Code 대화 전반에 걸쳐 진정한 컨텍스트 보존과 장기 프로젝트 연속성을 가능하게 합니다.\n\n##"
},
{
"path": "docs/user-guide-zh/agents.md",
"chars": 20416,
"preview": "# SuperClaude 智能体指南 🤖\n\nSuperClaude 提供了 14 个领域专业智能体，Claude Code 可以调用它们获得专业知识。\n\n\n## 🧪 测试智能体激活\n\n使用本指南之前，请验证智能体选择功能是否正常：\n\n``"
},
{
"path": "docs/user-guide-zh/commands.md",
"chars": 7929,
"preview": "# SuperClaude 命令指南\n\nSuperClaude 为 Claude Code 提供 21 个命令：用于工作流的 `/sc:*` 命令和用于专家的 `@agent-*`。\n\n## 命令类型\n\n| 类型 | 使用位置 | 格式 |"
},
{
"path": "docs/user-guide-zh/flags.md",
"chars": 7619,
"preview": "# SuperClaude 标志指南 🏁\n\n**大多数标志会自动激活** - Claude Code 读取行为指令，根据您请求中的关键词和模式来调用适当的上下文。\n\n## 基本自动激活标志（90% 的使用案例）\n\n### 核心分析标志\n| "
},
{
"path": "docs/user-guide-zh/mcp-servers.md",
"chars": 5305,
"preview": "# SuperClaude MCP 服务器指南 🔌\n\n## 概览\n\nMCP（模型上下文协议）服务器通过专业工具扩展 Claude Code 的能力。SuperClaude 集成了 6 个 MCP 服务器，并为 Claude 提供指令，告诉它"
},
{
"path": "docs/user-guide-zh/modes.md",
"chars": 13091,
"preview": "# SuperClaude 行为模式指南 🧠\n\n## ✅ 快速验证\n使用 `/sc:` 命令测试模式 - 它们会根据任务复杂性自动激活。有关完整命令参考，请参阅 [命令指南](commands.md)。\n\n## 快速参考表\n\n| 模式 | "
},
{
"path": "docs/user-guide-zh/session-management.md",
"chars": 4836,
"preview": "# 会话管理指南\n\nSuperClaude 通过 Serena MCP 服务器提供持久会话管理，实现在 Claude Code 对话中真正的上下文保存和长期项目连续性。\n\n## 具有持久内存的核心会话命令\n\n### `/sc:load` -"
},
{
"path": "install.sh",
"chars": 10572,
"preview": "#!/bin/bash\n################################################################################\n# SuperClaude Framework Ins"
},
{
"path": "package.json",
"chars": 1340,
"preview": "{\n \"name\": \"@bifrost_inc/superclaude\",\n \"version\": \"4.1.7\",\n \"description\": \"SuperClaude Framework NPM wrapper - Offi"
},
{
"path": "plugins/superclaude/__init__.py",
"chars": 0,
"preview": ""
},
{
"path": "plugins/superclaude/agents/__init__.py",
"chars": 0,
"preview": ""
},
{
"path": "plugins/superclaude/agents/backend-architect.md",
"chars": 2346,
"preview": "---\nname: backend-architect\ndescription: Design reliable backend systems with focus on data integrity, security, and fau"
},
{
"path": "plugins/superclaude/agents/business-panel-experts.md",
"chars": 9821,
"preview": "---\nname: business-panel-experts\ndescription: Multi-expert business strategy panel synthesizing Christensen, Porter, Dru"
},
{
"path": "plugins/superclaude/agents/deep-research-agent.md",
"chars": 4652,
"preview": "---\nname: deep-research-agent\ndescription: Specialist for comprehensive research with adaptive strategies and intelligen"
},
{
"path": "plugins/superclaude/agents/deep-research.md",
"chars": 1351,
"preview": "---\nname: deep-research\ndescription: Adaptive research specialist for external knowledge gathering\ncategory: analysis\n--"
},
{
"path": "plugins/superclaude/agents/devops-architect.md",
"chars": 2534,
"preview": "---\nname: devops-architect\ndescription: Automate infrastructure and deployment processes with focus on reliability and o"
},
{
"path": "plugins/superclaude/agents/frontend-architect.md",
"chars": 2402,
"preview": "---\nname: frontend-architect\ndescription: Create accessible, performant user interfaces with focus on user experience an"
},
{
"path": "plugins/superclaude/agents/learning-guide.md",
"chars": 2982,
"preview": "---\nname: learning-guide\ndescription: Teach programming concepts and explain code with focus on understanding through pr"
},
{
"path": "plugins/superclaude/agents/performance-engineer.md",
"chars": 2700,
"preview": "---\nname: performance-engineer\ndescription: Optimize system performance through measurement-driven analysis and bottlene"
},
{
"path": "plugins/superclaude/agents/pm-agent.md",
"chars": 21971,
"preview": "---\nname: pm-agent\ndescription: Self-improvement workflow executor that documents implementations, analyzes mistakes, an"
},
{
"path": "plugins/superclaude/agents/python-expert.md",
"chars": 3127,
"preview": "---\nname: python-expert\ndescription: Deliver production-ready, secure, high-performance Python code following SOLID prin"
},
{
"path": "plugins/superclaude/agents/quality-engineer.md",
"chars": 2787,
"preview": "---\nname: quality-engineer\ndescription: Ensure software quality through comprehensive testing strategies and systematic "
},
{
"path": "plugins/superclaude/agents/refactoring-expert.md",
"chars": 2946,
"preview": "---\nname: refactoring-expert\ndescription: Improve code quality and reduce technical debt through systematic refactoring "
},
{
"path": "plugins/superclaude/agents/repo-index.md",
"chars": 1448,
"preview": "---\nname: repo-index\ndescription: Repository indexing and codebase briefing assistant\ncategory: discovery\n---\n\n# Reposit"
},
{
"path": "plugins/superclaude/agents/requirements-analyst.md",
"chars": 2977,
"preview": "---\nname: requirements-analyst\ndescription: Transform ambiguous project ideas into concrete specifications through syste"
},
{
"path": "plugins/superclaude/agents/root-cause-analyst.md",
"chars": 3022,
"preview": "---\nname: root-cause-analyst\ndescription: Systematically investigate complex problems to identify underlying causes thro"
},
{
"path": "plugins/superclaude/agents/security-engineer.md",
"chars": 3064,
"preview": "---\nname: security-engineer\ndescription: Identify security vulnerabilities and ensure compliance with security standards"
},
{
"path": "plugins/superclaude/agents/self-review.md",
"chars": 1399,
"preview": "---\nname: self-review\ndescription: Post-implementation validation and reflexion partner\ncategory: quality\n---\n\n# Self Re"
},
{
"path": "plugins/superclaude/agents/socratic-mentor.md",
"chars": 12013,
"preview": "---\nname: socratic-mentor\ndescription: Educational guide specializing in Socratic method for programming knowledge with "
},
{
"path": "plugins/superclaude/agents/system-architect.md",
"chars": 2580,
"preview": "---\nname: system-architect\ndescription: Design scalable system architecture with focus on maintainability and long-term "
},
{
"path": "plugins/superclaude/agents/technical-writer.md",
"chars": 2847,
"preview": "---\nname: technical-writer\ndescription: Create clear, comprehensive technical documentation tailored to specific audienc"
},
{
"path": "plugins/superclaude/commands/__init__.py",
"chars": 0,
"preview": ""
},
{
"path": "plugins/superclaude/commands/agent.md",
"chars": 2777,
"preview": "name: sc:agent\ndescription: SC Agent — session controller that orchestrates investigation, implementation, and review\nca"
},
{
"path": "plugins/superclaude/commands/analyze.md",
"chars": 3258,
"preview": "---\nname: analyze\ndescription: \"Comprehensive code analysis across quality, security, performance, and architecture doma"
},
{
"path": "plugins/superclaude/commands/brainstorm.md",
"chars": 4945,
"preview": "---\nname: brainstorm\ndescription: \"Interactive requirements discovery through Socratic dialogue and systematic explorati"
},
{
"path": "plugins/superclaude/commands/build.md",
"chars": 3375,
"preview": "---\nname: build\ndescription: \"Build, compile, and package projects with intelligent error handling and optimization\"\ncat"
},
{
"path": "plugins/superclaude/commands/business-panel.md",
"chars": 2787,
"preview": "# /sc:business-panel - Business Panel Analysis System\n\n```yaml\n---\ncommand: \"/sc:business-panel\"\ncategory: \"Analysis & S"
},
{
"path": "plugins/superclaude/commands/cleanup.md",
"chars": 3626,
"preview": "---\nname: cleanup\ndescription: \"Systematically clean up code, remove dead code, and optimize project structure\"\ncategory"
},
{
"path": "plugins/superclaude/commands/design.md",
"chars": 3304,
"preview": "---\nname: design\ndescription: \"Design system architecture, APIs, and component interfaces with comprehensive specificati"
},
{
"path": "plugins/superclaude/commands/document.md",
"chars": 3270,
"preview": "---\nname: document\ndescription: \"Generate focused documentation for components, functions, APIs, and features\"\ncategory:"
},
{
"path": "plugins/superclaude/commands/estimate.md",
"chars": 3930,
"preview": "---\nname: estimate\ndescription: \"Provide development estimates for tasks, features, or projects with intelligent analysi"
},
{
"path": "plugins/superclaude/commands/explain.md",
"chars": 3779,
"preview": "---\nname: explain\ndescription: \"Provide clear explanations of code, concepts, and system behavior with educational clari"
},
{
"path": "plugins/superclaude/commands/git.md",
"chars": 2472,
"preview": "---\nname: git\ndescription: \"Git operations with intelligent commit messages and workflow optimization\"\ncategory: utility"
},
{
"path": "plugins/superclaude/commands/help.md",
"chars": 8196,
"preview": "---\nname: help\ndescription: \"List all available /sc commands and their functionality\"\ncategory: utility\ncomplexity: low\n"
},
{
"path": "plugins/superclaude/commands/implement.md",
"chars": 4378,
"preview": "---\nname: implement\ndescription: \"Feature and code implementation with intelligent persona activation and MCP integratio"
},
{
"path": "plugins/superclaude/commands/improve.md",
"chars": 3964,
"preview": "---\nname: improve\ndescription: \"Apply systematic improvements to code quality, performance, and maintainability\"\ncategor"
},
{
"path": "plugins/superclaude/commands/index-repo.md",
"chars": 2712,
"preview": "---\nname: sc:index-repo\ndescription: Repository Indexing - 94% token reduction (58K → 3K)\n---\n\n# Repository Index Creato"
}
]
// ... and 203 more files (download for full content)
About this extraction
This page contains the full source code of the SuperClaude-Org/SuperClaude_Framework GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 403 files (2.4 MB), approximately 656.7k tokens, and a symbol index with 327 extracted functions, classes, methods, constants, and types. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.