🚀 SuperCode Framework

Enhanced AI agent framework extending OpenCode capabilities with MCP integrations, behavioral flags, and modular architecture

---

🚀 Quickstart

Get SuperCode running in minutes with these simple steps:

Prerequisites

• Node.js 16.0.0 or higher
• npm (comes with Node.js)
• OpenCode with @opencode-ai/plugin installed

Installation

# Clone SuperCode framework
git clone https://github.com/niklasschaeffer/supercode-revised.git
cd supercode-revised

# Install dependencies
npm install

# Run the installation script
npm run supercode:init ${YOUR_PROJECT_FOLDER}

Your First Steps

# Load project context and activate framework
/load

# Try your first enhanced command with behavioral flags
/implement --ultrathink --orchestrate "create a user authentication system"

# Explore available agents
/spawn context-refinement

# Try project renovation with new command
/renovate --analyze "update project dependencies"

Verification

# Check initialization status
/initialize --status

# Verify context loading
/load --status

# Test agent coordination
/spawn orchestrator

✅ SuperCode is now ready! You have access to 11 MCP servers, behavioral flags, and complete agent ecosystem (19 agents + 13 commands) with dual MCP foundation established.

---

🎯 What is SuperCode?

SuperCode is a comprehensive AI agent framework that supercharges OpenCode with:

• 🔗 MCP Server Integrations: 13 powerful MCP servers for enhanced capabilities
• 🎛️ Behavioral Flags: Fine-grained control over AI execution modes
• 🤖 Modular Agent System: Specialized agents for specific tasks
• ⚡ Command System: Reusable commands for common workflows
• 📋 Template System: Standardized templates for consistency
• 🧠 Memory Management: Dual persistence with Knowledge Graph + Memory Bank

Perfect For

• 🏗️ Framework Development - Build complex systems with multi-agent coordination
• 🔧 Tool Integration - Seamlessly integrate external services and APIs
• 📚 Documentation Projects - Auto-generate and maintain comprehensive docs
• 🚀 Startup Prototyping - Rapidly build and iterate on complex features
• 🎯 Enterprise Applications - Build scalable, maintainable systems

---

✨ Core Features

🔗 MCP Server Integrations

SuperCode integrates 11 powerful MCP servers:

MCP Server	Purpose	Key Features
Knowledge Graph	Entity Memory	Persistent entity relationships, structured knowledge storage
Memory Bank	Project Memory	Multi-project memory management, structured documentation
Sequential	Multi-step Reasoning	Complex reasoning workflows, decision trees
Context7	Library Documentation	Official library docs, API references
Tavily	Web Search & Research	Real-time web search, content extraction
Playwright	Browser Automation	E2E testing, web scraping, browser control
Desktop Commander	System Operations	File system, terminal commands, local automation
Forgejo	Git Forge Integration	Repository management, CI/CD workflows
shadcn	UI Components	Component registry, design system
Prompt-Kit	Prompt Patterns	Reusable prompt templates
Chrome DevTools	Browser DevTools	Performance profiling, debugging

🎛️ Behavioral Flags

Control AI execution with powerful flags:

# Enhanced reasoning and analysis
--ultrathink

# Multi-agent coordination and parallel execution
--orchestrate

# Token-efficient execution
--token-efficient

# Security-focused implementation
--safe

# Pattern-based development
--patterns

# Performance-optimized execution
--performance

🤖 Agent System

Specialized agents for every task:

• 🎯 Orchestrator - Multi-agent coordination and task decomposition
• 🔍 Context-Refinement - Project intelligence and context optimization
• 🛠️ Backend-Engineer - API development and server-side logic
• 🎨 Frontend-Engineer - UI components and user experience
• 🔒 Security-Engineer - Security analysis and vulnerability assessment
• 🧪 QA-Engineer - Testing strategies and quality assurance
• ⚙️ System-Architect - System design and architectural planning
• 🔧 Refactoring-Expert - Code quality and technical debt reduction
• 🚀 DevOps-Engineer - Infrastructure and deployment automation
• 📊 Deep-Research-Specialist - Comprehensive research and analysis
• 🔄 Renovator - Project renovation and dependency management
• 📋 Task-Manager - Intelligent task decomposition and hierarchical management
• 🔍 Root-Cause-Analyst - Issue analysis and problem resolution
• 📱 Mobile-Optimization - Mobile-first development and responsive design
• 📝 Logging - System logging and monitoring implementation
• 🌿 Git-Specialist - Version control and Git workflow optimization
• ⚡ Generator-Specialist - Code generation and scaffolding automation
• 🗄️ Database Engineer - Database design and optimization across multiple systems
• 🐳 Docker Specialist - Containerization and orchestration best practices

⚡ Command System

Powerful commands for common workflows:

# Initialize project and establish dual MCP foundation
/initialize

# Load project context from memories + patterns
/load

# Save session context with constraint enforcement
/save

# Spawn specialized agents for complex tasks
/spawn

# Direct feature implementation with orchestration
/implement

# Build project compilation, packaging, and deployment preparation
/build

# Quality improvement and optimization
/improve

# Troubleshooting and debugging
/troubleshoot

# Code generation and scaffolding
/generate

# Project renovation and dependency management
/renovate

# Project cleanup and maintenance
/cleanup

# Task management and decomposition
/task

# Git operations and version control
/git

📋 Template System

Standardized templates for consistency:

• Agent Templates - For creating new specialized agents
• Command Templates - For extending command capabilities
• MCP Server Templates - For documenting new integrations
• Project Templates - For consistent project structure

---

🏗️ Architecture

Modular Design

SuperCode follows modular architecture principles:

supercode-revised/
├── agent/              # Agent definitions and configurations
├── command/            # Command implementations
├── templates/          # Standardized templates
├── docs/              # Generated documentation
├── landingpage/       # Web interface
├── opendocs/          # Open documentation system
└── .memory-bank/       # Project memories and structured documentation

Dual MCP Integration

Structured + Project Memory Systems:

• Knowledge Graph - Entity relationships for structured knowledge storage and retrieval
• Memory Bank - Project-based memory management with multi-project support
• Intelligent Coordination - Cross-system deduplication and complementary knowledge

Initialization Process: The /initialize command establishes this dual MCP foundation by:

• Setting up Knowledge Graph for entity relationship management
• Configuring Memory Bank for project-specific documentation
• Creating core memories and structured project files
• Setting up complete context management foundation

Memory Management

Optimized Memory System:

• 33% memory reduction through intelligent consolidation
• 2-3 session memory limit for sustainable development
• Pattern consolidation into single source of truth
• Automatic constraint enforcement without user intervention
• Foundation establishment through /initialize for optimal memory setup

---

🎯 Usage Examples

Project Initialization

# Complete project bootstrap with dual MCP foundation
/initialize

# Force relearn for existing projects
/initialize --force-relearn

# Skip analysis for quick setup
/initialize --skip-analysis

# Initialize with verbose output
/initialize --verbose

The Complete Workflow:

1. /initialize - CREATE foundation from scratch (establishes dual MCP integration)
2. /load - READ existing context from both MCPs
3. Work with framework - Use agents and commands for development
4. /save - WRITE completed work to both MCPs

Multi-Agent Orchestration

# Complex feature development with coordination
/implement --orchestrate --ultrathink "build a complete e-commerce system"

# This automatically:
# 1. 🎯 Orchestrator analyzes requirements and decomposes tasks
# 2. 🏗️ System-Architect designs architecture
# 3. 🛠️ Backend-Engineer builds APIs
# 4. 🎨 Frontend-Engineer creates UI components
# 5. 🔒 Security-Engineer adds authentication
# 6. 🧪 QA-Engineer implements testing

Context-Driven Development

# Initialize project foundation
/initialize

# Load comprehensive project context
/load

# Framework-aware implementation
/implement "add user authentication to existing API"

# Context-aware improvement
/improve --patterns "optimize database queries"

Research and Documentation

# Deep research with web integration
/spawn deep-research-specialist
/research --comprehensive "microservices best practices 2024"

# Auto-generate documentation
/generate --type docs --target "API endpoints"

Project Renovation and Maintenance

# Analyze and update project dependencies
/renovate --analyze --safe "update all dependencies"

# Renovate with orchestrator coordination
/renovate --orchestrate --ultrathink "comprehensive project renovation"

# Cleanup and maintenance
/cleanup --optimize "remove unused dependencies and files"

# Task-based renovation workflow
/task --decompose "renovate frontend dependencies"
/git --status "check renovation branch status"

Security and Quality

# Security-focused implementation
/implement --safe "payment processing system"

# Quality improvement with patterns
/improve --patterns --performance "legacy code refactoring"

# Comprehensive testing
/spawn qa-engineer
/test --coverage --integration "user workflows"

---

🛠️ Development Setup

Prerequisites

• Node.js 16.0.0+
• npm 7.0.0+
• Git 2.0.0+
• OpenCode with @opencode-ai/plugin

Development Installation

# Clone for development
git clone https://github.com/niklasschaeffer/supercode-revised.git
cd supercode-revised

# Install development dependencies
npm install

# Set up development environment
npm run supercode:init .

# Load development context
/load

# Verify setup
/spawn orchestrator

Project Structure

supercode-revised/
├── agent/                  # Agent definitions
│   ├── orchestrator.md     # Primary coordination agent
│   ├── context-gathering.md
│   ├── backend-engineer.md
│   └── ...
├── command/                # Command implementations
│   ├── load.md            # Context loading
│   ├── implement.md       # Feature implementation
│   └── ...
├── templates/              # Standardized templates
│   ├── agent.template.md
│   ├── command.template.md
│   └── ...
├── docs/                   # Generated documentation
├── landingpage/           # Web interface
├── opendocs/              # Open documentation
├── .memory-bank/          # Project memories and structured documentation
│   ├── memories/
│   └── ...
├── package.json           # Dependencies and scripts
├── install.sh             # Installation script
└── README.md              # This file

Configuration

Configuration is handled through:

• OpenCode Configuration (~/.config/opencode/)
• Environment Variables (optional)
• Project Settings (project.yml)

---

🧪 Testing and Quality

Built-in Quality Assurance

# Comprehensive testing with QA agent
/spawn qa-engineer
/test --comprehensive "entire system"

# Security validation
/spawn security-engineer
/audit --security "authentication system"

# Performance optimization
/spawn refactoring-expert
/optimize --performance "database operations"

Code Quality Standards

• SOLID Principles - Applied throughout framework
• Design Patterns - Factory, Builder, Decorator, Observer, Strategy
• TypeScript Best Practices - Strict typing and interfaces
• Testing Standards - Unit, integration, and E2E testing
• Security Guidelines - OWASP compliance and secure coding

---

📚 Documentation

Auto-Generated Documentation

SuperCode automatically maintains comprehensive documentation:

• API Documentation - Generated from code analysis
• Agent Guides - Auto-updated with capabilities
• MCP Integration Docs - Complete server documentation
• Architecture Documentation - System design and patterns

Living Documentation

# Generate current documentation
/generate --docs --comprehensive

# Create agent capability matrix
/generate --matrix --agents

---

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Workflow

# Fork and clone
git clone https://github.com/niklasschaeffer/supercode-revised.git

# Create feature branch
git checkout -b feature/amazing-feature

# Initialize and load context for development
/initialize
/load

# Make your changes
/implement --ultrathink "your amazing feature"

# Test thoroughly
/spawn qa-engineer
/test --comprehensive

# Submit pull request

Contribution Guidelines

• Follow Patterns - Use established patterns from patterns_discovered_consolidated
• Add Tests - Include comprehensive tests for new features
• Update Docs - Keep documentation current
• Memory Management - Follow memory optimization guidelines
• Security First - Ensure security compliance

Code Style

• TypeScript - Strict typing preferred
• Modular Design - Single responsibility principle
• Documentation - Clear, comprehensive documentation
• Testing - High test coverage required
• Patterns - Use established design patterns

---

📄 License

This project is licensed under MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• OpenCode Team - For amazing plugin system
• MCP Community - For powerful server ecosystem
• Contributors - Everyone who has contributed to this project
• Early Adopters - For valuable feedback and improvements

---

📞 Support

Getting Help

• Documentation - Check this README and generated docs
• Issues - GitHub Issues
• Discussions - GitHub Discussions

Quick Commands for Help

# Get help with commands
/help

# Check system status
/status

# Debug issues
/troubleshoot

# Load context for support
/load --debug

---

🎉 Ready to Supercharge Your Development?

Get started now:

git clone https://github.com/niklasschaeffer/supercode-revised.git
cd supercode-revised
npm install
npm run supercode:init ${YOUR_PROJECT_FOLDER}
/load

🚀 Welcome to future of AI-assisted development!

---

Built with ❤️ by SuperCode team