SuperCharged-Claude-Code-Upgrade/cognitive-core/README.md

🧠 Cognitive Enhancement Suite for Claude Code

Intelligent autonomous planning, safety filtering, and context awareness - adapted from HighMark-31/Cognitive-User-Simulation Discord bot

Version: 1.0.0 Author: Adapted by Claude from HighMark-31's Cognitive-User-Simulation License: Compatible with existing skill licenses

---

📚 Table of Contents

• Overview
• Features
• Installation
• Skills Included
• Usage
• Integration with Superpowers
• Examples
• Configuration
• Troubleshooting

---

🎯 Overview

The Cognitive Enhancement Suite adapts the advanced cognitive simulation logic from a Discord bot into powerful Claude Code skills. These skills provide:

• Autonomous task planning - Breaks down complex tasks automatically
• Multi-layer safety - Prevents security vulnerabilities and bad practices
• Context awareness - Adapts to your language, expertise, and project

Unlike the original Discord bot (which simulates human behavior), these skills are optimized for development workflows and integrate seamlessly with existing tools like Superpowers.

---

✨ Features

🤖 Autonomous Planning

• Analyzes task complexity automatically
• Selects optimal execution strategy
• Integrates with Superpowers workflows
• Adapts to your expertise level

🛡️ Safety Filtering

• Blocks hardcoded secrets/credentials
• Prevents SQL injection, XSS, CSRF
• Validates command safety
• Checks dependency security
• Enforces best practices

🌐 Context Awareness

• Multi-language support (12+ languages)
• Expertise level detection
• Project context understanding
• Personalized communication style

---

📦 Installation

Quick Install

All skills are already installed in your ~/.claude/skills/ directory:

~/.claude/skills/
├── cognitive-planner/
│   └── SKILL.md
├── cognitive-safety/
│   └── SKILL.md
├── cognitive-context/
│   └── SKILL.md
└── (your other skills)

Verify Installation

Check that skills are present:

ls -la ~/.claude/skills/cognitive-*/

Expected output:

cognitive-planner:
total 12
drwxr-xr-x  2 uroma uroma 4096 Jan 17 22:30 .
drwxr-xr-x 30 uroma uroma 4096 Jan 17 22:30 ..
-rw-r--r--  1 uroma uroma 8234 Jan 17 22:30 SKILL.md

cognitive-safety:
total 12
drwxr-xr-x  2 uroma uroma 4096 Jan 17 22:30 .
drwxr-xr-x 30 uroma uroma 4096 Jan 17 22:30 ..
-rw-r--r--  1 uroma uroma 7123 Jan 17 22:30 SKILL.md

cognitive-context:
total 12
drwxr-xr-x  2 uroma uroma 4096 Jan 17 22:30 .
drwxr-xr-x 30 uroma uroma 4096 Jan 17 22:30 ..
-rw-r--r--  1 uroma uroma 6542 Jan 17 22:30 SKILL.md

---

🧩 Skills Included

1. cognitive-planner

Purpose: Autonomous task planning and action selection

Activates when:

• You request building/creating something complex
• Task requires multiple steps
• You ask "how should I..." or "what's the best way to..."

What it does:

• Analyzes task complexity (Simple → Very Complex)
• Selects optimal approach (direct, planned, systematic)
• Integrates with Superpowers workflows
• Presents options for complex tasks

Example output:

## 🧠 Cognitive Planner Analysis

**Task Type**: Feature Implementation
**Complexity**: MODERATE
**Interest Level**: 0.7 (HIGH)
**Recommended Approach**: Plan then execute with TDD

**Context**:
- Tech stack: Python/Django detected
- Superpowers available
- Existing tests in codebase

**Confidence**: 0.8

**Action Plan**:
1. Use /superpowers:write-plan for task breakdown
2. Implement with TDD approach
3. Verify with existing test suite

**Activating**: Superpowers write-plan skill

---

2. cognitive-safety

Purpose: Code and content safety filtering

Activates when:

• Writing any code
• Suggesting bash commands
• Generating configuration files
• Providing credentials/secrets

What it does:

• Blocks hardcoded secrets/passwords
• Prevents SQL injection, XSS, CSRF
• Validates command safety
• Checks for security vulnerabilities
• Enforces best practices

Example protection:

❌ WITHOUT COGNITIVE-SAFETY:
   password = "my_password_123"

✅ WITH COGNITIVE-SAFETY:
   password = os.getenv('DB_PASSWORD')
   # Add to .env file: DB_PASSWORD=your_secure_password

   ⚠️ SECURITY: Never hardcode credentials in code!

---

3. cognitive-context

Purpose: Enhanced context awareness

Activates when:

• Analyzing user messages
• Detecting language
• Assessing expertise level
• Understanding project context

What it does:

• Auto-detects language (12+ supported)
• Assesses expertise (beginner/intermediate/expert)
• Understands project tech stack
• Adapts communication style
• Provides personalized responses

Example adaptation:

BEGINNER USER:
"How do I add a login system?"

→ Cognitive-Context detects beginner level
→ Provides detailed, educational response
→ Explains each step clearly
→ Links to learning resources
→ Uses analogies and examples

EXPERT USER:
"How do I optimize N+1 queries in GraphQL?"

→ Cognitive-Context detects expert level
→ Provides concise, technical answer
→ Shows code immediately
→ Discusses advanced considerations
→ Assumes deep understanding

---

🚀 Usage

Automatic Activation

All cognitive skills activate automatically when needed. No special commands required.

Manual Activation

You can explicitly invoke skills if needed:

# For complex planning
"I want to build a REST API with authentication. Use cognitive-planner to break this down."

# For safety review
"Review this code for security issues using cognitive-safety."

# For context-aware help
"Explain how Docker works. Adapt to my level."

Combined with Superpowers

The cognitive skills work best with Superpowers:

# User request
"Add user authentication to my Flask app"

# Cognitive flow
1. cognitive-planner analyzes:
   - Task type: Feature Implementation
   - Complexity: MODERATE
   - Approach: Plan with Superpowers

2. Activates Superpowers:
   - /superpowers:write-plan (create task breakdown)
   - /superpowers:execute-plan (TDD implementation)

3. cognitive-safety protects:
   - No hardcoded secrets
   - Proper password hashing
   - Secure session management

4. cognitive-context adapts:
   - Detects your expertise level
   - Provides appropriate detail
   - Uses your preferred language

---

🔗 Integration with Superpowers

How They Work Together

┌─────────────────────────────────────────┐
│         COGNITIVE PLANNER                │
│  (Analyzes complexity → Selects approach) │
└──────────────┬───────────────────────────┘
               │
               ↓
        ┌──────────────┐
        │ SUPERPOWERS  │
        │ (Systematic   │
        │  execution)   │
        └──────┬───────┘
               │
               ↓
┌──────────────────────────────────────────┐
│          COGNITIVE SAFETY                 │
│  (Validates security → Blocks bad code)   │
└──────────────────────────────────────────┘

       ↑                              ↑
       │                              │
┌──────┴────────┐           ┌────────┴──────┐
│ COGNITIVE     │           │     YOUR       │
│ CONTEXT       │←─────────→│  CODEBASE     │
│ (Adapts to    │           │               │
│  your level)  │           │               │
└───────────────┘           └───────────────┘

Complementary Features

Feature	Superpowers	Cognitive Skills	Combined
Planning	Manual plans	Autonomous complexity analysis	Auto-select optimal approach
TDD	Test-first enforcement	Security-focused tests	Secure test-driven development
Quality	Code quality	Security validation	High-quality, secure code
Debugging	Systematic process	Vulnerability detection	Security-aware debugging
Context	Codebase awareness	User expertise awareness	Full context understanding

---

📖 Examples

Example 1: Building a Feature

User request:

"Add a comment system to my blog"

Cognitive response:

## 🧠 Cognitive Planner Analysis

**Task Type**: Feature Implementation
**Complexity**: MODERATE (database, models, views, templates)
**Interest Level**: HIGH (explicit request)
**Recommended Approach**: Plan with Superpowers, then TDD

**Confidence**: 0.75

**Action Plan**:
1. Use /superpowers:write-plan to break down task
2. Implement models (Comment, Post relation)
3. Create views and templates
4. Add form validation
5. Write tests (TDD approach)
6. cognitive-safety: Validate input sanitization

**Activating**: Superpowers write-plan skill

---

## 🔒 Safety Considerations

cognitive-safety will ensure:
- No SQL injection (parameterized queries)
- XSS prevention (escape output)
- CSRF protection on forms
- Input validation and sanitization
- Rate limiting considerations

---

## 💡 Context Adaptation

Detected: Intermediate developer
Response style: Balanced explanation with code examples
Language: English

---

Example 2: Fixing a Bug

User request:

"The login isn't working, it just shows an error"

Cognitive response:

## 🧠 Cognitive Planner Analysis

**Task Type**: Bug Fixing
**Complexity**: MODERATE (need to reproduce first)
**Interest Level**: HIGH (explicit bug report)
**Recommended Approach**: Systematic debugging

**Confidence**: 0.6 (need more info)

**Action Plan**:
1. Use /superpowers:debug-plan for systematic investigation
2. Reproduce the error
3. Isolate the location
4. Identify root cause
5. Fix with test
6. Verify solution

**Questions to clarify**:
- What error message do you see?
- What happens step-by-step?
- Browser console errors?
- Server logs?

---

## 🛡️ Safety During Debugging

cognitive-safety will:
- Prevent exposing sensitive data in error messages
- Ensure error logging doesn't leak credentials
- Validate any fixes don't introduce vulnerabilities

---

## 💡 Context Adaptation

Detected: Need more information
Response style: Asking clarifying questions

---

Example 3: Non-English Speaker

User request:

"Necesito agregar un sistema de login a mi aplicación"

Cognitive response:

## 🧠 Cognitive Planner Analysis

**Tipo de tarea**: Implementación de características
**Complejidad**: MODERADA
**Nivel de interés**: ALTO
**Enfoque recomendado**: Planificar con Superpowers

**Idioma detectado**: Español 🇪🇸

**Plan de acción**:
1. Usar /superpowers:write-plan para planificar
2. Implementar modelos de usuario
3. Crear sistema de autenticación
4. Añadir hash de contraseñas seguro
5. Escribir pruebas
6. cognitive-safety: Validar seguridad

---

## 🔒 Consideraciones de Seguridad

cognitive-safety asegurará:
- Contraseñas hasheadas con bcrypt/argon2
- Sin contraseñas en código duro
- Tokens de sesión seguros
- Protección contra fuerza bruta

---

## 💡 Adaptación de Contexto

Nivel detectado: Intermedio
Estilo de respuesta: Explicación equilibrada en español
Idioma: Español

---

⚙️ Configuration

Default Behavior

The cognitive skills work out-of-the-box with sensible defaults:

# cognitive-planner defaults
complexity_threshold: moderate
auto_activate_superpowers: true
confidence_threshold: 0.7

# cognitive-safety defaults
block_hardcoded_secrets: true
prevent_sql_injection: true
prevent_xss: true
validate_commands: true
check_dependencies: true

# cognitive-context defaults
auto_detect_language: true
auto_detect_expertise: true
adapt_communication_style: true

Customization (Optional)

You can customize behavior by adding environment variables:

# ~/.env or project .env
COGNITIVE_PLANNER_THRESHOLD=high
COGNITIVE_SAFETY_STRICT_MODE=true
COGNITIVE_CONTEXT_DEFAULT_LANGUAGE=english

---

🐛 Troubleshooting

Skills Not Activating

Problem: Cognitive skills aren't triggering

Solutions:

# 1. Verify skills are installed
ls -la ~/.claude/skills/cognitive-*/

# 2. Check file permissions
chmod +r ~/.claude/skills/cognitive-*/SKILL.md

# 3. Restart Claude Code
# Close and reopen terminal/editor

Language Detection Issues

Problem: Wrong language detected

Solution:

Explicitly specify language:
"Explain this in Spanish: cómo funciona Docker"

Expertise Mismatch

Problem: Too much/little explanation

Solution:

Specify your preferred level:
"Explain this like I'm a beginner"
"Give me the expert-level explanation"
"Keep it concise, I'm a developer"

Safety Blocks

Problem: Safety filter blocking legitimate code

Solution:

Acknowledge the safety warning:
"I understand this is for development only"
Then cognitive-safety will allow with warning

---

📚 Advanced Usage

For Plugin Developers

Integrate cognitive skills into your own plugins:

# Example: Custom plugin using cognitive skills
def my_custom_command(user_input):
    # Use cognitive-planner
    complexity = analyze_complexity(user_input)

    # Use cognitive-safety
    if not is_safe(user_input):
        return "Unsafe: " + get_safety_reason()

    # Use cognitive-context
    expertise = detect_expertise(user_input)
    language = detect_language(user_input)

    # Adapt response
    return generate_response(
        complexity=complexity,
        expertise=expertise,
        language=language
    )

Creating Workflows

Combine cognitive skills with other tools:

# Example workflow: Feature development
workflow:
  name: "Feature Development"
  steps:
    1. cognitive-planner: Analyze complexity
    2. If complex:
         - brainstorm: Explore options
         - cognitive-planner: Create detailed plan
    3. cognitive-safety: Review approach
    4. Execute with Superpowers TDD
    5. cognitive-safety: Validate code
    6. cognitive-context: Format documentation

---

🤝 Contributing

These skills are adapted from the original Cognitive-User-Simulation Discord bot by HighMark-31.

Original Source

• Repository: https://github.com/HighMark-31/Cognitive-User-Simulation
• Original Author: HighMark-31
• Original License: Custom (educational/experimental)

Adaptations Made

• Converted Discord bot logic to Claude Code skills
• Adapted cognitive simulation for development workflows
• Enhanced security patterns for code safety
• Added multi-language support for developers
• Integrated with Superpowers plugin ecosystem

---

📄 License

Adapted from the original Cognitive-User-Simulation project.

The original Discord bot is for educational and research purposes only. This adaptation maintains that spirit while providing value to developers.

---

🙏 Acknowledgments

• HighMark-31 - Original cognitive simulation framework
• Superpowers Plugin - Systematic development methodology
• Claude Code - AI-powered development environment

---

📞 Support

For issues or questions:

1. Check this README for solutions
2. Review individual SKILL.md files
3. Open an issue in your local environment
4. Consult the original Discord bot repo for insights

---

Made with 🧠 for smarter development

⭐ Enhances every Claude Code session ⭐