cc-enhance/README.md

Adaptive prompt intelligence with 25-step selection, CLAUDE.md adherence, MCP tool orchestration, parallel execution and memory integration for Claude Code

# CC-Enhance

<div align="center">

![CC-Enhance - From confusion to clarity with AI assistance](assets/hero.jpeg)

<h3>Adaptive prompt intelligence: 25-step selection, rule adherence, tool orchestration, parallel execution & memory</h3>

[![npm version](https://badge.fury.io/js/cc-enhance.svg)](https://www.npmjs.com/package/cc-enhance)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Security](https://img.shields.io/badge/Security-Policy-blue.svg)](./SECURITY.md)

<img src="assets/icons/icon-package.png" width="48" height="48" alt="NPM" style="vertical-align: middle;"> **[View on NPM](https://www.npmjs.com/package/cc-enhance)** | <img src="assets/icons/icon-tools.png" width="48" height="48" alt="Install" style="vertical-align: middle;"> **[Installation](#installation)** | <img src="assets/icons/icon-docs.png" width="48" height="48" alt="Docs" style="vertical-align: middle;"> **[Documentation](#usage)**

Dynamically enhances prompts using intelligent risk-based selection from 25 specialized steps. Features CLAUDE.md rule adherence, MCP tool recommendations, parallel execution optimization (🔄), memory search integration, agent detection, and contrarian analysis - ensuring Claude Code maintains context and delivers results 3-4x faster.

</div>

## The Context Adherence Problem <img src="assets/icons/icon-brain.png" width="48" height="48" alt="Brain" style="vertical-align: middle;">

Claude Code struggles to maintain project context throughout conversations. You have a detailed CLAUDE.md with project rules, but Claude often:

- **Forgets project guidelines** mid-conversation
- **Ignores file organization rules** when creating new files
- **Loses track of coding standards** over time
- **Requires constant reminders** about project conventions

**Solution**: The `/enhance` command transforms vague requests into comprehensive, context-aware prompts with contrarian analysis to challenge assumptions early.

## New Features <img src="assets/icons/icon-rocket.png" width="48" height="48" alt="Rocket" style="vertical-align: middle;">

### Agent Detection & Recommendations
- **Automatically detects** available Claude Code agents (user and project level)
- **Recommends existing agents** that match your task type
- **Proposes new agent creation** when no suitable agent exists
- **Smart complexity detection** - only suggests agents for complex multi-step tasks

### Parallel Execution Optimization
- **Marks parallelizable tasks** with <img src="assets/icons/icon-cycle.png" width="32" height="32" alt="Cycle" style="vertical-align: middle;"> indicator
- **Guides parallel Task execution** for improved performance
- **Clear instructions** for running multiple Task invocations simultaneously
- **Dramatic speed improvements** for multi-step operations

<details>
<summary><strong>📚 Additional Information</strong> (click to expand)</summary>

## How It Works

### Before and After

**Before** (what you type):
```
implement user authentication with OAuth
```

**After** `/enhance` (what Claude receives):
```
Enhanced Prompt: Implement OAuth Authentication System

DETECTED TASK TYPE:
Primary intent: Implementation
Risk level: High (authentication/security)
Complexity: Multi-component system

INTELLIGENT STEP SELECTION:
Applied 15 of 25 steps based on security requirements
[Steps: 1,2,3,5,6,7,8,9,10,11,12,13,16,18,23]

MEMORY & PAST SOLUTIONS:
- Search claude-self-reflect for "OAuth implementation" 🔄
- Check git history for auth patterns 🔄
- Review similar implementations in codebase 🔄

EXTERNAL TOOLS & RESOURCES:
- mcp_zen for security review
- context7 for OAuth2 documentation
- grep MCP for GitHub OAuth examples
- claude-self-reflect for past auth discussions

PROJECT RULES (from CLAUDE.md):
- NEVER store secrets in code
- ALWAYS use environment variables for keys
- Document security decisions

AGENT RECOMMENDATIONS:
- Use 'security-reviewer' agent for audit
- Consider 'api-designer' for contract validation

REQUIREMENTS (Parallel Operations):
- Set up OAuth provider configuration 🔄
- Implement token management 🔄
- Create user session handling 🔄
- Add security middleware 🔄
- Write integration tests 🔄
- Document authentication flow

CONTRARIAN ANALYSIS:
- Is OAuth overkill for this use case?
- Could simpler JWT suffice?
- What's the recovery plan for provider outages?

EDGE CASES & SECURITY:
- Token refresh failures
- Provider API changes
- Rate limiting scenarios
- CSRF protection
- Session hijacking prevention

SUCCESS CRITERIA:
- [ ] Secure token storage implemented
- [ ] All auth flows tested (login/logout/refresh)
- [ ] Security audit passed (mcp_zen review)
- [ ] Performance < 200ms auth checks
- [ ] Zero security warnings in scan
- [ ] Documentation complete with diagrams
```

## Features

<img src="assets/icons/icon-checkmark.png" width="32" height="32" alt="Check" style="vertical-align: middle;"> **Two-pass enhancement** - First expands using Claude's best practices, then adds CLAUDE.md rules  
<img src="assets/icons/icon-checkmark.png" width="32" height="32" alt="Check" style="vertical-align: middle;"> **Contrarian analysis** - Questions assumptions early to prevent wasted effort  
<img src="assets/icons/icon-checkmark.png" width="32" height="32" alt="Check" style="vertical-align: middle;"> **Context engineering** - Selects only relevant project rules  
<img src="assets/icons/icon-checkmark.png" width="32" height="32" alt="Check" style="vertical-align: middle;"> **CLAUDE.md integration** - Automatically includes applicable guidelines  
<img src="assets/icons/icon-checkmark.png" width="32" height="32" alt="Check" style="vertical-align: middle;"> **Smart detection** - Understands task type from your request  
<img src="assets/icons/icon-checkmark.png" width="32" height="32" alt="Check" style="vertical-align: middle;"> **MCP tool recommendations** - Suggests appropriate tools based on context  
<img src="assets/icons/icon-checkmark.png" width="32" height="32" alt="Check" style="vertical-align: middle;"> **Works in plan mode** - Compatible with Claude's planning features (Shift+P)

## Installation

```bash
npm install -g cc-enhance
```

The `/enhance` command will be automatically installed to `~/.claude/commands/` and ready to use in Claude Code.

## Usage

In Claude Code:

```bash
/enhance create a deployment guide
# → Comprehensive prompt with relevant CLAUDE.md rules included

/enhance fix the login bug
# → Debugging-focused prompt with contrarian analysis

/enhance implement user authentication
# → Implementation prompt with edge cases and robustness checks
```

**<img src="assets/icons/icon-lightbulb.png" width="32" height="32" alt="Tip" style="vertical-align: middle;"> Pro Tip**: Use Shift+P (plan mode) with `/enhance` to review the enhanced prompt before execution.

## How the /enhance Command Works

1. **Reads CLAUDE.md** - Automatically finds and incorporates your project rules
2. **Detects Task Type** - Analyzes keywords to understand what you're trying to do
3. **Intelligent Step Selection** - Dynamically selects from 25 specialized enhancement steps based on task complexity
4. **Adds Contrarian Analysis** - Questions assumptions early to prevent wasted effort
5. **Agent Detection** - Scans for available agents and recommends or proposes new ones
6. **Parallel Execution** - Marks tasks with <img src="assets/icons/icon-cycle.png" width="20" height="20" alt="Cycle" style="vertical-align: middle;"> for simultaneous execution
7. **Maps to MCP Tools** - Recommends appropriate tools like mcp**zen** for analysis
8. **Generates Structured Prompt** - Creates comprehensive requirements with success criteria
9. **Presents for Review** - Shows the enhanced prompt in plan mode for your approval

## How Intelligent Selection Works

The `/enhance` command uses a sophisticated selection system that adapts to your request's complexity:

### Risk-Based Selection
- **Low Risk** (typos, docs): 4-5 essential steps only
- **Medium Risk** (features): 8-10 steps including validation
- **High Risk** (auth, payments): 12-15 steps with security checks
- **Critical** (production): 15+ steps with comprehensive coverage

### The 25-Step Dictionary
The system selects from specialized enhancement steps including:
- **Foundation Steps**: Clarity, context, examples, parallel operations
- **Core Steps**: Requirements parsing, contrarian analysis, solution design
- **Validation Steps**: Testing strategy, code review, rollback planning
- **Domain Steps**: Security audits, migrations, performance, compliance

### Example Selections
- `"fix typo in README"` → Selects only 4 steps (basic clarity and context)
- `"add login feature"` → Selects 12 steps (includes security, validation, edge cases)
- `"database migration"` → Selects 10 steps (includes rollback, data validation, testing)
- `"production deployment"` → Selects 18+ steps (comprehensive validation and monitoring)

Tasks marked with <img src="assets/icons/icon-cycle.png" width="32" height="32" alt="Cycle" style="vertical-align: middle;"> can run in parallel for dramatic speed improvements.

</details>

## Recommended Tools <img src="assets/icons/icon-toolbox.png" width="48" height="48" alt="Tools" style="vertical-align: middle;">

Build your ultimate Claude Code toolbelt with these complementary tools:

### Memory & Context
- **[claude-self-reflect](https://github.com/ramakay/claude-self-reflect)** - 100+ ⭐ - Claude forgets everything. This fixes that.
  - Search past conversations with semantic understanding
  - 100% local by default - your data stays private
  - Project-scoped search with time-based memory decay
  - Perfect complement to cc-enhance for maintaining long-term context

### File Organization
- **[claude-organizer](https://github.com/ramakay/claude-organizer)** - Automatic file organization for Claude Code
  - CC-Enhance handles prompt enhancement
  - Claude-Organizer handles file organization
  - Use together for the complete Claude Code experience!

### Documentation & Search
- **[context7](https://context7.com)** - Real-time documentation search
  - Get up-to-date library documentation
  - Code examples from actual usage
  - Integrates with cc-enhance recommendations

### Code Search
- **[grep (MCP)](https://github.com/anthropics/mcp-servers)** - GitHub code search
  - Find real-world code examples
  - Search across millions of repositories
  - Pattern-based code discovery

## Why Separate from claude-organizer?

This project was originally part of claude-organizer but has been separated to:
- Allow independent development and versioning
- Keep each tool focused on its core functionality
- Enable users to choose which features they need
- Follow the Single Responsibility Principle

## FAQ

<details>
<summary>🤔 Isn't CLAUDE.md enough? Why do I need this tool?</summary>

### The honest answer:

You're absolutely right to be skeptical! CLAUDE.md is indeed powerful and often sufficient. Let's be contrarian about our own tool:

**When cc-enhance actually adds value:**
- **Complex multi-step tasks** - When you need 10+ coordinated actions with validation
- **Contrarian thinking** - Challenges assumptions BEFORE you waste 2 hours coding the wrong solution
- **Parallel execution optimization** - Identifies tasks that can run simultaneously (marked with 🔄)
- **Risk-appropriate validation** - Automatically adds security checks for auth, skips them for typos
- **Consistency across sessions** - Same request always generates similarly thorough prompts

**When you DON'T need cc-enhance:**
- Simple one-line fixes or typo corrections
- When your CLAUDE.md is comprehensive and Claude already follows it well
- Quick questions or explanations
- When you prefer manual control over every instruction
- If you enjoy the back-and-forth clarification dance with Claude

The tool exists because even with great CLAUDE.md files, Claude can still lose context mid-conversation. This tool front-loads that context into every request.

</details>

<details>
<summary>📊 How does intelligent selection actually work?</summary>

### The Selection Algorithm

The tool analyzes your request through multiple lenses:

1. **Risk Assessment** - Detects keywords like "production", "payment", "auth", "database"
2. **Complexity Detection** - Estimates scope from verbs like "implement", "refactor", "migrate"
3. **Context Mapping** - Matches request to relevant CLAUDE.md sections
4. **Step Selection** - Picks from 25 specialized steps based on the above

**Example Decision Tree:**
```
Request: "fix the login bug"
├─ Contains "fix" + "bug" → Debugging context
├─ Contains "login" → Security context
├─ Risk: Medium-High (auth involved)
└─ Selected steps: [1,2,7,8,9,11,12,16] (8 steps)
   Including: security audit, test strategy, contrarian analysis
```

</details>

<details>
<summary>🚀 What makes this different from just being verbose?</summary>

### Intelligence vs Verbosity

**Verbose approach:** Add everything possible to every prompt (exhausting and inefficient)

**Intelligent approach:** Select only relevant enhancements based on context

Example:
- `"Update README"` → 4 steps (just clarity and context)
- `"Implement OAuth"` → 15 steps (security, testing, edge cases, rollback plans)

The tool knows when to be brief and when to be thorough.

</details>

<details>
<summary>⚡ How do parallel operations work?</summary>

### Parallel Execution with 🔄

When the tool marks steps with 🔄, it means they can run simultaneously:

```
REQUIREMENTS:
- Run test suite 🔄
- Check lint errors 🔄
- Validate types 🔄
- Review security scan results 🔄
```

Instead of running these sequentially (taking 4x longer), Claude can invoke multiple Task agents simultaneously, dramatically reducing execution time.

</details>

<details>
<summary>🎯 When should I use --debug mode?</summary>

### Debug Mode Usage

Use `/enhance --debug <request>` when you want to:
- See exactly which steps were selected and why
- Understand the risk assessment for your request
- Learn how the tool interprets different requests
- Troubleshoot why certain enhancements were included/excluded

Debug mode shows the complete decision process, making the "intelligent" part transparent.

</details>

<details>
<summary>🔧 Can I customize the enhancement steps?</summary>

### Customization Options

Currently, the 25-step dictionary is built-in, but you can:
- Use `--debug` to see all steps and understand selection
- Modify your CLAUDE.md to influence which project rules are included
- Contribute new steps via GitHub pull requests

Future versions may support custom step dictionaries per project.

</details>

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## License

Distributed under the MIT License. See [LICENSE](LICENSE) for more information.

## Support

- <img src="assets/icons/icon-clipboard.png" width="32" height="32" alt="Issues" style="vertical-align: middle;"> [Report Issues](https://github.com/ramakay/cc-enhance/issues)
- <img src="assets/icons/icon-chat.png" width="32" height="32" alt="Chat" style="vertical-align: middle;"> [Discussions](https://github.com/ramakay/cc-enhance/discussions)

---

<div align="center">
Made with <img src="assets/icons/icon-heart.png" width="32" height="32" alt="Love" style="vertical-align: middle;"> by <a href="https://github.com/ramakay">Rama Annaswamy</a>
</div>