Mithun Gowda B
116e9fc5f9
* fix: fill implementation gaps across core modules - Replace ConfidenceChecker placeholder methods with real implementations that search the codebase for duplicates, verify architecture docs exist, check research references, and validate root cause specificity - Fix intelligent_execute() error capture: collect actual errors from failed tasks instead of hardcoded None, format tracebacks as strings, and fix variable shadowing bug where loop var overwrote task parameter - Implement ReflexionPattern mindbase integration via HTTP API with graceful fallback when service is unavailable - Fix .gitignore: remove duplicate entries, add explicit !-rules for .claude/settings.json and .claude/skills/, remove Tests/ ignore - Remove unnecessary sys.path hack in cli/main.py - Fix FailureEntry.from_dict to not mutate input dict - Add comprehensive execution module tests: 62 new tests covering ParallelExecutor, ReflectionEngine, SelfCorrectionEngine, and the intelligent_execute orchestrator (136 total, all passing) https://claude.ai/code/session_01AnGJMAA6Qp2j9WKKHHZfB9 * chore: include test-generated reflexion artifacts https://claude.ai/code/session_01AnGJMAA6Qp2j9WKKHHZfB9 * fix: address 5 open GitHub issues (#536, #537, #531, #517, #534) Security fixes: - #536: Remove shell=True and user-controlled $SHELL from _run_command() to prevent arbitrary code execution. Use direct list-based subprocess.run without passing full os.environ to child processes. - #537: Add SHA-256 integrity verification for downloaded docker-compose and mcp-config files. Downloads are deleted on hash mismatch. Gateway config supports pinned hashes via docker_compose_sha256/mcp_config_sha256. Bug fixes: - #531: Add agent file installation to `superclaude install` and `update` commands. 20 agent markdown files are now copied to ~/.claude/agents/ alongside command installation. - #517: Fix MCP env var flag from --env to -e for API key passthrough, matching the Claude CLI's expected format. Usability: - #534: Replace Japanese trigger phrases and report labels in pm-agent.md and pm.md (both src/ and plugins/) with English equivalents for international accessibility. https://claude.ai/code/session_01AnGJMAA6Qp2j9WKKHHZfB9 * docs: align documentation with Claude Code and fix version/count gaps - Update CLAUDE.md project structure to include agents/ (20 agents), modes/ (7 modes), commands/ (30 commands), skills/, hooks/, mcp/, and core/ directories. Add Claude Code integration points section. - Fix version references: 4.1.5 -> 4.2.0 in installation.md, quick-start.md, and package.json (was 4.1.7) - Fix feature counts across all docs: - Commands: 21 -> 30 - Agents: 14/16 -> 20 - Modes: 6 -> 7 - MCP Servers: 6 -> 8 - Update README.md agent count from 16 to 20 - Add docs/user-guide/claude-code-integration.md explaining how SuperClaude maps to Claude Code's native features (commands, agents, hooks, skills, settings, MCP servers, pytest plugin) https://claude.ai/code/session_01AnGJMAA6Qp2j9WKKHHZfB9 * chore: update test-generated reflexion log https://claude.ai/code/session_01AnGJMAA6Qp2j9WKKHHZfB9 * docs: comprehensive Claude Code gap analysis and integration guide - Rewrite docs/user-guide/claude-code-integration.md with full feature mapping: all 28 hook events, skills system with YAML frontmatter, 5 settings scopes, permission rules, plan mode, extended thinking, agent teams, voice, desktop features, and session management. Includes detailed gap table showing where SuperClaude under-uses Claude Code capabilities (skills migration, hooks integration, plan mode, settings profiles). - Add Claude Code native features section to CLAUDE.md with extension points we use vs should use more (hooks, skills, plan mode, settings) - Add Claude Code integration gap analysis to KNOWLEDGE.md with prioritized action items for skills migration, hooks leverage, plan mode integration, and settings profiles https://claude.ai/code/session_01AnGJMAA6Qp2j9WKKHHZfB9 * chore: update test-generated reflexion log https://claude.ai/code/session_01AnGJMAA6Qp2j9WKKHHZfB9 * chore: bump version to 4.3.0 Bump version across all 15 files: - VERSION, pyproject.toml, package.json - src/superclaude/__init__.py, src/superclaude/__version__.py - CLAUDE.md, PLANNING.md, TASK.md, CHANGELOG.md - README.md, README-zh.md, README-ja.md, README-kr.md - docs/getting-started/installation.md, quick-start.md - docs/Development/pm-agent-integration.md Also fixes __version__.py which was out of sync at 0.4.0. Adds comprehensive CHANGELOG entry for v4.3.0. https://claude.ai/code/session_01AnGJMAA6Qp2j9WKKHHZfB9 * i18n: replace all Japanese/Chinese text with English in source files Replace CJK text with English across all non-translation files: - src/superclaude/commands/pm.md: 38 Japanese strings in PDCA cycle, error handling patterns, anti-patterns, document templates - src/superclaude/agents/pm-agent.md: 20 Japanese strings in PDCA phases, self-evaluation, documentation sections - plugins/superclaude/: synced from src/ copies - .github/workflows/readme-quality-check.yml: all Chinese comments, table headers, report strings, and PR comment text - .github/workflows/pull-sync-framework.yml: Japanese comment - .github/PULL_REQUEST_TEMPLATE.md: complete rewrite from Japanese Translation files (README-ja.md, docs/user-guide-jp/, etc.) are intentionally kept in their respective languages. https://claude.ai/code/session_01AnGJMAA6Qp2j9WKKHHZfB9 --------- Co-authored-by: Claude <noreply@anthropic.com>
12 KiB
Claude Code Integration Guide
How SuperClaude integrates with — and extends — Claude Code's native features.
Overview
SuperClaude enhances Claude Code through context engineering. It doesn't replace Claude Code — it configures and extends it with specialized commands, agents, modes, and development patterns through Claude Code's native extension points.
This guide maps every SuperClaude feature to its Claude Code integration point, and identifies gaps where SuperClaude could better leverage Claude Code's capabilities.
Integration Points
1. Slash Commands → Claude Code Custom Commands
Claude Code native: Reads .md files from ~/.claude/commands/ and makes them available as / commands. Supports YAML frontmatter, argument substitution ($ARGUMENTS, $0, $1), dynamic context injection (!`command`), and subagent execution (context: fork).
SuperClaude provides: 30 slash commands installed to ~/.claude/commands/sc/, namespaced as /sc:*.
| Category | Commands |
|---|---|
| Planning & Design | /sc:pm, /sc:brainstorm, /sc:design, /sc:estimate, /sc:spec-panel |
| Development | /sc:implement, /sc:build, /sc:improve, /sc:cleanup, /sc:explain |
| Testing & Quality | /sc:test, /sc:analyze, /sc:troubleshoot, /sc:reflect |
| Documentation | /sc:document, /sc:help |
| Version Control | /sc:git |
| Research | /sc:research, /sc:business-panel |
| Project Management | /sc:task, /sc:workflow |
| Utilities | /sc:agent, /sc:index-repo, /sc:recommend, /sc:select-tool, /sc:spawn, /sc:load, /sc:save |
Installation: superclaude install
2. Agents → Claude Code Custom Subagents
Claude Code native: Supports custom subagent definitions in ~/.claude/agents/ (user) and .claude/agents/ (project). Agents have YAML frontmatter with model, allowed-tools, effort, context, and hooks fields. Invocable via @agent-name syntax. 6 built-in subagents: Explore, Plan, General-purpose, Bash, statusline-setup, Claude Code Guide.
SuperClaude provides: 20 domain-specialist agents installed to ~/.claude/agents/.
| Agent | Specialization |
|---|---|
@pm-agent |
Project management, PDCA cycles, context persistence |
@system-architect |
System design, architecture decisions |
@frontend-architect |
UI/UX, component design, accessibility |
@backend-architect |
APIs, databases, infrastructure |
@security-engineer |
Security audit, vulnerability analysis |
@deep-research |
Multi-source research with citations |
@deep-research-agent |
Alternative research agent |
@quality-engineer |
Testing strategy, code quality |
@performance-engineer |
Optimization, profiling, benchmarks |
@python-expert |
Python-specific best practices |
@technical-writer |
Documentation, API docs |
@devops-architect |
CI/CD, deployment, infrastructure |
@refactoring-expert |
Code refactoring patterns |
@requirements-analyst |
Requirements engineering |
@root-cause-analyst |
Root cause analysis |
@socratic-mentor |
Teaching through questions |
@learning-guide |
Learning path guidance |
@self-review |
Code self-review |
@repo-index |
Repository indexing |
@business-panel-experts |
Business stakeholder analysis |
Installation: superclaude install (installs both commands and agents)
3. Behavioral Modes
Claude Code native: Supports permission modes (default, plan, acceptEdits, bypassPermissions), effort levels (low, medium, high, max), and extended thinking. No direct "behavioral mode" concept — SuperClaude adds this through context injection.
SuperClaude provides: 7 behavioral modes that adapt Claude's response patterns:
| Mode | Effect | Claude Code Mapping |
|---|---|---|
| Brainstorming | Divergent thinking, idea generation | Context injection via command |
| Business Panel | Multi-stakeholder analysis | Multi-agent orchestration |
| Deep Research | Systematic investigation with citations | Extended thinking + research agent |
| Introspection | Self-reflection, meta-analysis | Extended thinking context |
| Orchestration | Multi-agent coordination | Subagent delegation |
| Task Management | PDCA cycles, progress tracking | TodoWrite + session persistence |
| Token Efficiency | Minimal token usage, concise responses | Effort level adjustment |
4. Skills → Claude Code Skills System
Claude Code native: Full skills system with YAML frontmatter (name, description, allowed-tools, model, effort, context, agent, hooks), argument substitution, dynamic context injection, subagent execution, and auto-discovery in .claude/skills/ directories. Skills can be user-invocable or auto-triggered.
SuperClaude provides: 1 skill currently (confidence-check). This is a significant gap — many SuperClaude commands could be reimplemented as proper Claude Code skills for better integration.
Installation: superclaude install-skill <name>
5. Hooks → Claude Code Hooks System
Claude Code native: 28 hook event types with 4 handler types (command, HTTP, prompt, agent). Events include SessionStart, SessionEnd, PreToolUse, PostToolUse, Stop, SubagentStart, SubagentStop, UserPromptSubmit, PreCompact, PostCompact, TaskCompleted, WorktreeCreate, and more. Hooks are configured in settings.json under the hooks key.
SuperClaude provides: Hook definitions in src/superclaude/hooks/hooks.json. Currently limited — does not leverage many available hook events.
Gap: SuperClaude could use hooks for:
SessionStart— Auto-restore PM Agent contextPostToolUse— Self-check validation after editsStop— Session summary and next-actions persistenceTaskCompleted— Reflexion pattern triggerSubagentStop— Quality gate checks
6. Settings → Claude Code Settings System
Claude Code native: 5 settings scopes (managed, CLI flags, local project, shared project, user). Supports permissions (allow/ask/deny), tool-specific rules with wildcards (Bash(npm *), Edit(/path/**)), sandbox configuration, model overrides, auto-memory, and MCP server management.
SuperClaude provides: Project-level .claude/settings.json with basic permission rules.
Gap: Could provide recommended settings profiles for different workflows (e.g., strict security mode, autonomous development mode, research mode).
7. MCP Servers → Claude Code MCP Integration
Claude Code native: Supports stdio and SSE transports, OAuth authentication, 3 configuration scopes (local, project, user), tool search, channel push notifications, and elicitation (interactive input). 60+ servers in the official registry.
SuperClaude provides: 8 pre-configured servers + AIRIS Gateway:
| Server | Purpose | Transport |
|---|---|---|
| AIRIS Gateway | Unified gateway with 60+ tools | SSE |
| Tavily | Web search for deep research | stdio |
| Context7 | Official library documentation | stdio |
| Sequential Thinking | Multi-step problem solving | stdio |
| Playwright | Browser automation and E2E testing | stdio |
| Serena | Semantic code analysis | stdio |
| Magic | UI component generation | stdio |
| MorphLLM | Fast Apply for code modifications | stdio |
Installation: superclaude mcp (interactive) or superclaude mcp --servers tavily context7
8. Pytest Plugin (Auto-loaded)
Claude Code native: No built-in test framework — relies on tool use (Bash) to run tests.
SuperClaude adds: Auto-loaded pytest plugin registered via pyproject.toml entry point.
Fixtures: confidence_checker, self_check_protocol, reflexion_pattern, token_budget, pm_context
Auto-markers: Tests in /unit/ → @pytest.mark.unit, /integration/ → @pytest.mark.integration
Custom markers: confidence_check, self_check, reflexion, complexity
Feature Mapping: Claude Code ↔ SuperClaude
| Claude Code Feature | SuperClaude Enhancement | Gap? |
|---|---|---|
60+ built-in / commands |
30 custom /sc:* commands |
Complementary |
| 6 built-in subagents | 20 domain-specialist @agents |
Complementary |
| Skills system (YAML + MD) | 1 skill (confidence-check) | Large gap — should convert commands to skills |
| 28 hook events | Basic hook definitions | Large gap — most events unused |
| 5 settings scopes | 1 project scope used | Medium gap — no recommended profiles |
| Permission modes (4) | Not leveraged | Gap — could provide mode presets |
| Extended thinking | Deep Research mode uses it | Partial |
| Agent teams (preview) | Orchestration mode | Partial alignment |
| Voice dictation (20 langs) | Not leveraged | Not applicable |
| Desktop app features | Not leveraged | Not applicable (CLI-focused) |
| Plan mode | Not leveraged | Gap — could integrate with confidence checks |
| Session persistence | PM Agent memory files | Partial — could use native sessions |
/compact context mgmt |
Token Efficiency mode | Partial alignment |
| MCP 60+ registry servers | 8 pre-configured + gateway | Partial |
| Worktree isolation | Documented in CLAUDE.md | Documented |
--effort levels |
Token Efficiency mode | Partial alignment |
/batch parallel changes |
Parallel execution engine | Complementary |
| Fast mode | Not leveraged | Not applicable |
Key Gaps to Address
High Priority
-
Skills Migration: Convert key
/sc:*commands into proper Claude Code skills with YAML frontmatter. This enables auto-triggering, tool restrictions, effort overrides, and better IDE integration. -
Hooks Integration: Leverage Claude Code's 28 hook events for:
SessionStart→ PM Agent context restorationStop→ Session summary persistencePostToolUse→ Self-check after editsTaskCompleted→ Reflexion pattern
-
Plan Mode Integration: Connect confidence checks with Claude Code's native plan mode — block implementation when confidence < 70%.
Medium Priority
-
Settings Profiles: Provide recommended
.claude/settings.jsonprofiles for different workflows (strict security, autonomous dev, research). -
Native Session Persistence: Use Claude Code's
--continue/--resumeinstead of custom memory files for PM Agent context. -
Permission Presets: Pre-configured permission rules for SuperClaude's common workflows.
Future (v5.0+)
- TypeScript Plugin System: Native Claude Code plugin marketplace distribution.
- IDE Extensions: VS Code / JetBrains integration for SuperClaude features.
- Agent Teams: Align Orchestration mode with Claude Code's agent teams feature.
Claude Code Native Features Reference
For developers working on SuperClaude, these are the key Claude Code capabilities to be aware of:
| Feature | Documentation |
|---|---|
| Custom commands | ~/.claude/commands/*.md with YAML frontmatter |
| Custom agents | ~/.claude/agents/*.md with model/tools/effort config |
| Skills | ~/.claude/skills/ with auto-discovery and argument substitution |
| Hooks | 28 events in settings.json → command/HTTP/prompt/agent handlers |
| Settings | 5 scopes: managed > CLI > local > shared > user |
| Permissions | Bash(pattern), Edit(path), mcp__server__tool rules |
| MCP | stdio/SSE transports, OAuth, 3 scopes, elicitation |
| Subagents | Agent tool with model/tools/isolation/background options |
| Plan mode | Read-only exploration, visual plan markdown |
| Extended thinking | --effort max, Alt+T toggle, MAX_THINKING_TOKENS |
| Voice | 20 languages, push-to-talk, /voice command |
| Session mgmt | Named sessions, resume, fork, 7-day persistence |
| Context | /context visualization, auto-compaction at ~95% |