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

Cognitive Enhancement Suite - Integration Guide

Quick Start Verification

Test that your cognitive skills are working:

# Start a new Claude Code session
# Then ask:

"Use cognitive-planner to analyze this task: Add user registration"

# Expected response:
# - Complexity analysis
# - Approach recommendation
# - Integration with Superpowers

---

Skill Interaction Matrix

User Request	cognitive-planner	cognitive-safety	cognitive-context	Superpowers
"Build a REST API"	✅ Analyzes complexity	✅ Validates security	✅ Detects expertise	✅ TDD execution
"Fix this bug"	✅ Selects debugging approach	✅ Checks for vulnerabilities	✅ Adapts explanation	✅ Systematic debug
"Review this code"	✅ Assesses review depth	✅ Security scan	✅ Detail level	⚠️ Optional
"Add comments"	⚠️ Simple task	✅ No secrets in comments	✅ Language adaptation	❌ Not needed
"Deploy to production"	✅ Complex planning	✅ Config validation	✅ Expert-level	⚠️ Optional

---

Real-World Workflows

Workflow 1: Feature Development

USER: "Add a payment system to my e-commerce site"

↓ COGNITIVE-PLANNER activates
   → Analyzes: COMPLEX task
   → Detects: Security critical
   → Recommends: Detailed plan + Superpowers
   → Confidence: 0.6 (needs clarification)

↓ CLAUDE asks questions
   "What payment provider? Stripe? PayPal?"
   "What's your tech stack?"

↓ USER answers
   "Stripe with Python Django"

↓ COGNITIVE-PLANNER updates
   → Confidence: 0.85
   → Plan: Use Superpowers TDD
   → Security: Critical (PCI compliance)

↓ COGNITIVE-SAFETY activates
   → Blocks: Hardcoded API keys
   → Requires: Environment variables
   → Validates: PCI compliance patterns
   → Warns: Never log card data

↓ SUPERPOWERS executes
   → /superpowers:write-plan
   → /superpowers:execute-plan
   → TDD throughout

↓ COGNITIVE-CONTEXT adapts
   → Language: English
   → Expertise: Intermediate
   → Style: Balanced with security focus

Result: Secure, tested payment integration

Workflow 2: Bug Fixing

USER: "Users can't upload files, getting error 500"

↓ COGNITIVE-PLANNER activates
   → Analyzes: MODERATE bug fix
   → Recommends: Systematic debugging
   → Activates: Superpowers debug workflow

↓ SUPERPOWERS:DEBUG-PLAN
   Phase 1: Reproduce
   Phase 2: Isolate
   Phase 3: Root cause
   Phase 4: Fix & verify

↓ During fixing:
   COGNITIVE-SAFETY checks:
   - No hardcoded paths
   - Proper file validation
   - No directory traversal
   - Secure file permissions

↓ COGNITIVE-CONTEXT:
   → Detects: Intermediate developer
   → Provides: Clear explanations
   → Shows: Why each step matters

Result: Systematic fix, security verified, learning achieved

Workflow 3: Code Review

USER: "Review this code for issues"

[User provides code snippet]

↓ COGNITIVE-PLANNER
   → Analyzes: Code review task
   → Depth: Based on code complexity

↓ COGNITIVE-SAFETY scans:
   ✅ Check: Hardcoded secrets
   ✅ Check: SQL injection
   ✅ Check: XSS vulnerabilities
   ✅ Check: Command injection
   ✅ Check: File operations
   ✅ Check: Dependencies
   ✅ Check: Error handling

↓ COGNITIVE-CONTEXT
   → Expertise: Developer (code review)
   → Style: Technical, direct
   → Focus: Security + best practices

↓ Response includes:
   1. Security issues (if any)
   2. Best practice violations
   3. Performance considerations
   4. Maintainability suggestions
   5. Positive feedback on good patterns

Result: Comprehensive security-focused code review

---

Integration with Always-Use-Superpowers

If you use the auto-superpowers skill, cognitive skills integrate seamlessly:

USER MESSAGE
    ↓
[ALWAYS-USE-SUPERPOWERS]
    ↓
Check: Does any Superpowers skill apply?
    ↓
YES → Activate Superpowers skill
    ↓
[COGNITIVE-PLANNER]
    ↓
Assess: Task complexity
    ↓
IF COMPLEX:
    → Use detailed Superpowers workflow
IF SIMPLE:
    → Direct execution (skip overhead)
    ↓
[COGNITIVE-SAFETY]
    ↓
Validate: All code/commands
    ↓
IF SAFE:
    → Proceed
IF UNSAFE:
    → Block or warn
    ↓
[COGNITIVE-CONTEXT]
    ↓
Adapt: Response to user
    ↓
OUTPUT

---

Example Sessions

Session 1: Beginner Building First API

USER: "I want to build an API for my todo app"

🧠 COGNITIVE-PLANNER:
Task: Feature Implementation
Complexity: MODERATE
Approach: Plan then build
Confidence: 0.7

💡 COGNITIVE-CONTEXT:
Level: BEGINNER detected
Style: Educational, detailed
Language: English

🛡️ COGNITIVE-SAFETY:
Will ensure: No secrets in code, proper validation

📋 ACTION PLAN:
1. Clarify requirements
2. Choose framework (Flask/Django/Express)
3. Plan endpoints
4. Implement with Superpowers TDD
5. Security validation

💬 Let me ask you some questions:
- What programming language do you prefer?
- Have you built an API before?
- What features should it have?

USER: "Python, no this is my first one, just CRUD for todos"

🧠 COGNITIVE-PLANNER UPDATE:
Confidence: 0.9
Plan: Use Flask (beginner-friendly)
Superpowers: Activate TDD workflow

💡 COGNITIVE-CONTEXT ADAPTATION:
Beginner → Will explain each step
Show examples
Link to resources

📚 IMPLEMENTATION PLAN:
1. Set up Flask project structure
2. Create Todo model
3. Implement endpoints (POST, GET, PUT, DELETE)
4. Add input validation
5. Write tests (TDD)
6. Security check (cognitive-safety)

🛡️ SECURITY CONSIDERATIONS:
- Input validation (prevent injection)
- Error handling (don't leak internals)
- CORS if needed
- Rate limiting basics

Ready to start? I'll guide you through each step.

Session 2: Expert Optimizing Performance

USER: "Optimize this slow database query"

[Provides query with N+1 problem]

🧠 COGNITIVE-PLANNER:
Task: Optimization (Expert level)
Complexty: MODERATE
Approach: Direct analysis

💡 COGNITIVE-CONTEXT:
Level: EXPERT detected
Style: Concise, technical

🔍 ANALYSIS:
Query: SELECT * FROM posts WHERE user_id = X
Problem: N+1 queries in loop
Impact: O(n) database calls

⚡ SOLUTION:
```python
# ❌ BEFORE (N+1)
posts = db.query('SELECT * FROM posts WHERE user_id = ?', user_id)
for post in posts:
    comments = db.query('SELECT * FROM comments WHERE post_id = ?', post.id)
    post.comments = comments

# ✅ AFTER (Single query with JOIN)
posts = db.query('''
    SELECT p.*, c.*
    FROM posts p
    LEFT JOIN comments c ON c.post_id = p.id
    WHERE p.user_id = ?
''', user_id)

📊 Performance:

• Before: 1 + N queries
• After: 1 query
• Improvement: O(n) → O(1)

🛡️ COGNITIVE-SAFETY: ✅ Parameterized query (SQL injection safe) ✅ No hardcoded values ✅ Proper error handling needed

💡 CONSIDERATIONS:

• For large datasets: Use pagination
• For complex relations: Consider ORM batching
• For read-heavy: Add caching layer

Want me to implement this with proper error handling?

### Session 3: Multilingual Support

USER: "Je veux ajouter une page de connexion"

🌐 COGNITIVE-CONTEXT: Language: FRENCH detected 🇫🇷 Expertise: Intermediate Style: Balanced, in French

🧠 COGNITIVE-PLANNER: Tâche: Implémentation de fonctionnalité Complexité: MODÉRÉE Approche: Planifier avec Superpowers

📋 PLAN D'ACTION:

1. Créer le modèle User
2. Implémenter l'authentification
3. Créer la page de connexion
4. Ajouter la validation
5. Tests TDD
6. Sécurité (cognitive-safety)

🛡️ SÉCURITÉ:

• Hashage bcrypt pour les mots de passe
• Pas de secrets en dur
• Protection CSRF
• Validation des entrées

💡 EXEMPLE DE CODE:

# login route
@app.route('/login', methods=['POST'])
def login():
    username = request.form.get('username')
    password = request.form.get('password')

    # Validation
    if not username or not password:
        return 'Missing credentials', 400

    # Authentification
    user = User.query.filter_by(username=username).first()
    if user and bcrypt.check_password_hash(user.password, password):
        login_user(user)
        return redirect('/dashboard')

    return 'Invalid credentials', 401

Voulez-vous que je mette en œuvre cela avec des tests?

---

## Customization

### Adjusting Complexity Threshold

```bash
# ~/.env
COGNITIVE_PLANNER_THRESHOLD=low  # Plan more tasks
COGNITIVE_PLANNER_THRESHOLD=high  # Plan only complex tasks

Safety Strict Mode

# ~/.env
COGNITIVE_SAFETY_STRICT_MODE=true  # Block all potentially unsafe
COGNITIVE_SAFETY_STRICT_MODE=false # Warn but allow

Language Preference

# ~/.env
COGNITIVE_CONTEXT_DEFAULT_LANGUAGE=spanish

---

Troubleshooting Integration

Problem: Skills conflict

SYMPTOM: Multiple skills trying to handle same task

SOLUTION: Skills have priority order
1. cognitive-planner (analyzes first)
2. cognitive-safety (validates)
3. cognitive-context (adapts)
4. Superpowers (executes)

If conflict: cognitive-planner decides which to use

Problem: Too much planning overhead

SYMPTOM: Every task gets planned, even simple ones

SOLUTION: Adjust threshold
# ~/.env
COGNITIVE_PLANNER_AUTO_SIMPLE=true  # Auto-handle simple tasks
COGNITIVE_PLANNER_SIMPLE_THRESHOLD=5  # <5 minutes = simple

Problem: Safety too strict

SYMPTOM: Legitimate code gets blocked

SOLUTION:
1. Acknowledge you understand risk
2. cognitive-safety will allow with warning
3. Or set strict mode in .env

---

Performance Impact

Cognitive skills add minimal overhead:

WITHOUT COGNITIVE SKILLS:
User request → Immediate execution

WITH COGNITIVE SKILLS:
User request → Context analysis (0.1s)
             → Complexity check (0.1s)
             → Safety validation (0.2s)
             → Execution
             → Total overhead: ~0.4s

BENEFIT: Prevents hours of debugging, security issues

---

Best Practices

1. Trust the analysis

   • cognitive-planner assesses complexity accurately
   • Use its recommendations

2. Heed safety warnings

   • cognitive-safety prevents real vulnerabilities
   • Don't ignore warnings

3. Let it adapt

   • cognitive-context learns from you
   • Respond naturally, it will adjust

4. Use with Superpowers

   • Best results when combined
   • Planning + TDD + Safety = Quality

5. Provide feedback

   • If expertise level is wrong, say so
   • If language is wrong, specify
   • Skills learn and improve

---

FAQ

Q: Do I need to activate these skills? A: No, they activate automatically when needed.

Q: Will they slow down my workflow? A: Minimal overhead (~0.4s), but prevent major issues.

Q: Can I disable specific skills? A: Yes, remove or rename the SKILL.md file.

Q: Do they work offline? A: Yes, all logic is local (no API calls).

Q: Are my code snippets sent anywhere? A: No, everything stays on your machine.

Q: Can I add my own patterns? A: Yes, edit the SKILL.md files to customize.

---

Next Steps

1. ✅ Skills installed
2. ✅ Integration guide read
3. → Start using Claude Code normally
4. → Skills will activate when needed
5. → Adapt and provide feedback

---

Happy coding with enhanced cognition! 🧠