# ⚡ Supercharged Dev

[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-compatible-purple)](https://modelcontextprotocol.io)

---

**English** · [中文](#chinese)

---

> **Your AI coder burns $200/month on junk tokens. This MCP server makes it think first, test first, compress first. 11 tools, one install.**

---

## The Problem

AI coding assistants are great at generating code fast. But:

| Without Supercharged Dev | With Supercharged Dev |
|--------------------------|----------------------|
| Jumps straight to code without clarifying what you actually want | **Designs first** — asks the right questions before writing a single line |
| Writes production code with no tests, hoping it works | **Tests first** — RED → GREEN → REFACTOR, every time |
| Guesses at bug fixes, changes random things, makes it worse | **Debugs systematically** — finds the root cause before touching anything |
| Submits PRs with no self-review, wasting your time | **Reviews itself** — 5-dimension check before showing you the diff |
| Burns tokens on verbose JSON, logs, and boilerplate | **Compresses** — saves 60–95% of tokens before they reach the LLM |

---

## What You Get (In One Picture)

```
You: "Add a login page"
      │
      ▼
AI calls brainstorm_design ──→ "Who are the users? What auth method?
                                What happens on failure? Let me propose 2 approaches..."
      │ (you approve the design)
      ▼
AI calls decompose_task ──→ Task 1: Create src/auth/login.tsx
                             Task 2: Add src/auth/__tests__/login.test.tsx
                             Task 3: Wire up route in app.tsx
                             (each task: 2-5 min, verifiable)
      │
      ▼
AI calls generate_test_skeleton ──→ "Here's a failing test for the login component.
                                     Run it first — it should fail. Then I'll implement."
      │ (test fails ✓)
      ▼
AI implements, then calls review_code_diff ──→ "Self-review:
                                                 ✓ Plan Compliance
                                                 ✓ Correctness
                                                 ⚠ Edge Cases — missing empty password case"
      │ (fixes the edge case)
      ▼
You get tested, reviewed, production-ready code.
```

---

## When Do You Actually Use Each Tool?

| Scenario | Tool to call | What happens |
|----------|-------------|--------------|
| **"I want to add a feature but I'm not sure about the approach"** | `brainstorm_design` | Walks you through clarifying questions, proposes 2–3 approaches with tradeoffs |
| **"I have a design doc, now make a plan"** | `decompose_task` | Breaks it into 2–5 minute tasks. Each has a file path, code, and verification step |
| **"Just wrote a bunch of code, is it any good?"** | `review_code_diff` | 5-dimension review. Critical issues block progress. |
| **"Something's broken and I have no idea why"** | `debug_root_cause` | 4-phase process. Won't let you fix anything until you've proven the root cause. |
| **"I need to write tests for this"** | `generate_test_skeleton` | RED → GREEN → REFACTOR workflow. Test first, code second. |
| **"This API response is 10,000 lines of JSON"** | `compress_content` | Compresses to ~2,000 tokens. Same answer quality. Saves money. |
| **"How much have I saved so far?"** | `compression_stats` | Shows total tokens, savings %, cache hit rate, session runtime. |
| **"What skills are available?"** | `list_skills` | Shows all 13 Superpowers skills with descriptions and trigger conditions. |

---

## 11 MCP Tools

### 🧠 Workflow (5 tools)

| Tool | What it does |
|------|-------------|
| `brainstorm_design` | Socratic design exploration. Refuses to code until you've approved an approach. |
| `decompose_task` | Design spec → 2–5 min executable sub-tasks with file paths and verification steps. |
| `review_code_diff` | Self-review across 5 dimensions: Plan Compliance, Correctness, Testing, Edge Cases, Style. |
| `debug_root_cause` | 4-phase debugging. Gate at each phase. No fixes until root cause is proven. |
| `generate_test_skeleton` | RED → GREEN → REFACTOR. Generates a failing test before you write any production code. |

### 📖 Knowledge (3 tools)

| Tool | What it does |
|------|-------------|
| `get_skill` | Returns the full Markdown of any Superpowers skill — injectable into any AI instruction. |
| `list_skills` | Lists all 13 available skills with descriptions. Discover what's possible. |
| `get_preset_info` | Shows what's in each preset (minimal/default/aggressive). |

### 🔧 Compression (3 tools)

| Tool | What it does | Typical savings |
|------|-------------|:---:|
| `compress_content` | Compresses content (Headroom or fallback). Auto-detects JSON/code/text. | 50–92% |
| `retrieve_original` | Pulls original content back from LRU cache if the LLM needs it. | — |
| `compression_stats` | Live stats: total requests, tokens saved, cache hit rate, engine, uptime. | — |

---

## Skills Library (13 Skills)

| # | Skill | Automatically triggers when... |
|---|-------|-------------------------------|
| 1 | `brainstorming` | You ask for any new feature or behavior change |
| 2 | `writing-plans` | A design has been approved |
| 3 | `subagent-driven-development` | Tasks need independent, isolated execution |
| 4 | `executing-plans` | You want batch execution with checkpoints |
| 5 | `test-driven-development` | Any production code is about to be written |
| 6 | `systematic-debugging` | A bug is reported |
| 7 | `verification-before-completion` | Someone claims a fix is done |
| 8 | `requesting-code-review` | A task is marked complete |
| 9 | `receiving-code-review` | Review feedback is received |
| 10 | `using-git-worktrees` | Code is about to be written in an existing project |
| 11 | `finishing-a-development-branch` | All tasks on a branch are done |
| 12 | `dispatching-parallel-agents` | Multiple independent modules need work |
| 13 | `writing-skills` | A new skill needs to be created |

---

## Who Is This For?

- **Solo developers** who want the discipline of a senior engineering team in their AI assistant
- **Teams** who want consistent code quality across AI-generated contributions
- **Anyone tired of $200+ Claude bills** — compression pays for itself in a day
- **MCP power users** who want one server that covers the full dev workflow
- **AI coding skeptics** — add guardrails so the AI doesn't run wild

---

## Quick Start

```bash
# 1. Install
pip install supercharged-dev

# 2. Start the MCP server
supercharged mcp serve

# 3. Print the config for your client
supercharged mcp config
```

### Claude Desktop

```json
{
  "mcpServers": {
    "supercharged": {
      "command": "uvx",
      "args": ["supercharged-dev", "mcp", "serve"]
    }
  }
}
```

### Project Setup (Copies skill files + generates config)

```bash
cd your-project
supercharged init --preset aggressive
```

---

## Presets

| Preset | Skills | Compression | For |
|--------|:------:|:-----------:|-----|
| `minimal` | 3 | ❌ | Just the essentials: brainstorm, TDD, review |
| `default` | 9 | ❌ | Full workflow minus advanced features |
| `aggressive` | 13 | ✅ | Everything. Maximum discipline, minimum spend. |

---

## Compression (Optional Dependency)

```bash
pip install supercharged-dev[compress]
```

| Content type | Typical savings |
|-------------|:---:|
| JSON API responses / MCP tool output | 70–86% |
| Code search results (100 hits) | 92% |
| Server logs | 90%+ |
| Full agent sessions (10+ tool calls) | 85% |

No quality loss — compressed content produces the same answers (verified on GSM8K, TruthfulQA, SQuAD).

---

<a name="chinese"></a>

## 中文说明

### 这是什么？

一个 MCP Server，让你的 AI 编程助手学会**先思考再写代码、先测试再上线、先压缩再花钱**。

**它解决的问题：**

| 没装之前 | 装了之后 |
|---------|---------|
| AI 上来就写代码，不管你到底想要什么 | 先用苏格拉底式提问理清设计，批准后才动工 |
| 没有测试的保护，代码靠"祈祷" | TDD 铁律：RED → GREEN → REFACTOR |
| Debug 靠猜，改来改去越改越糟 | 系统化四阶段调试，找到根因前禁止修复 |
| 提 PR 不审查，浪费你时间 | 5 维度自审查，Critical 问题阻塞进度 |
| JSON/日志/模板白白烧 Token | 压缩 60–95%，答案质量不变，账单大幅下降 |

### 典型用法

| 当你想... | 调用这个工具 | 会发生什么 |
|----------|------------|----------|
| 加功能但不确定怎么做 | `brainstorm_design` | 挨个提问帮你理清需求，提 2–3 个方案让你选 |
| 把设计方案落地 | `decompose_task` | 拆成 2–5 分钟的小任务，每个都有文件路径和验证步骤 |
| 刚写的代码质量怎么样 | `review_code_diff` | 5 个维度逐一审查，Critical 问题会阻止继续 |
| 出 bug 了不知道原因 | `debug_root_cause` | 四阶段流程，不找到根因不准修复 |
| 需要写测试 | `generate_test_skeleton` | 先生成会失败的测试，然后写最少代码让它通过 |
| API 返回了一万行 JSON | `compress_content` | 压到 ~2000 token，省 70–86%，答案质量不变 |
| 想看省了多少钱 | `compression_stats` | 实时统计：总请求、Token 节省、缓存命中率 |

### 11 个 MCP 工具

| 类别 | 工具 | 一句话 |
|------|------|--------|
| 🧠 工作流 | `brainstorm_design` | 写代码前先想清楚 |
| 🧠 工作流 | `decompose_task` | 设计 → 可执行任务 |
| 🧠 工作流 | `review_code_diff` | 5 维度自我审查 |
| 🧠 工作流 | `debug_root_cause` | 根因不明不修复 |
| 🧠 工作流 | `generate_test_skeleton` | 先写失败的测试 |
| 📖 知识 | `get_skill` | 读取任意 skill 文档 |
| 📖 知识 | `list_skills` | 列出全部 13 个 skill |
| 📖 知识 | `get_preset_info` | 查看预设配置 |
| 🔧 压缩 | `compress_content` | 压缩省 Token |
| 🔧 压缩 | `retrieve_original` | 从缓存取回原文 |
| 🔧 压缩 | `compression_stats` | 省钱统计 |

### 适合谁用？

- **独立开发者** — 一个人也有团队的工程纪律
- **团队** — 保证 AI 生成的代码质量一致
- **心疼账单的人** — 压缩省的钱可能比工具本身贵得多
- **MCP 重度用户** — 一个 Server 覆盖完整开发流程
- **对 AI 编程有顾虑的人** — 加上护栏，不让 AI 放飞自我

### 快速开始

```bash
pip install supercharged-dev
supercharged mcp serve
```

---

## License

MIT · Built on [Superpowers](https://github.com/obra/superpowers) and [Headroom](https://github.com/chopratejas/headroom).