SuperCharged-Claude-Code-Upgrade/skills/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](#overview)
- [Features](#features)
- [Installation](#installation)
- [Skills Included](#skills-included)
- [Usage](#usage)
- [Integration with Superpowers](#integration-with-superpowers)
- [Examples](#examples)
- [Configuration](#configuration)
- [Troubleshooting](#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:

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

### Verify Installation

Check that skills are present:

```bash
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:

```bash
# 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:**
```markdown
## 🧠 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:**
```markdown
## 🧠 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:**
```markdown
## 🧠 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:

```yaml
# 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:

```bash
# ~/.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:**
```bash
# 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:

```python
# 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:

```yaml
# 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

---

<div align="center">

**Made with 🧠 for smarter development**

⭐ **Enhances every Claude Code session** ⭐

</div>