https://github.com/devondragon/ccmagic
Claude Code Enablement Framework
https://github.com/devondragon/ccmagic
Last synced: 3 months ago
JSON representation
Claude Code Enablement Framework
- Host: GitHub
- URL: https://github.com/devondragon/ccmagic
- Owner: devondragon
- License: apache-2.0
- Created: 2025-08-11T00:34:26.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-02-23T16:46:30.000Z (4 months ago)
- Last Synced: 2026-02-24T00:31:04.164Z (4 months ago)
- Size: 337 KB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.markdown
- License: LICENSE
Awesome Lists containing this project
README
# ccmagic - Advanced Project Management Commands for Claude Code
A powerful collection of custom slash commands that transform Claude Code into a comprehensive project management system. Maintain organized context, track work progress, manage features and tasks, and enable seamless handoffs between development sessions.
**Now with Claude Code's latest features**: Parallel subagents, real-time TodoWrite integration, and optional MCP tool enhancements.
## 🚀 Quick Start
### Installation
#### Option 1: Global Installation (User-wide)
1. Navigate to your Claude commands directory:
```bash
cd ~/.claude/commands/
```
2. Clone the ccmagic repository:
```bash
git clone https://github.com/devondragon/ccmagic.git
```
3. Start using commands with the `/ccmagic:` prefix in Claude Code!
#### Option 2: Project-local Installation
For team projects or when you want CCMagic versioned with your codebase:
**Using Git Submodule (Recommended for version control):**
```bash
# From your project root
git submodule add https://github.com/devondragon/ccmagic.git .claude/commands/ccmagic
git commit -m "Add CCMagic as submodule"
# Team members can initialize after cloning
git submodule update --init --recursive
```
**Using Direct Copy (Simpler, no submodule complexity - but no updates):**
```bash
# From your project root
mkdir -p .claude/commands
# Download and extract (using curl)
curl -L https://github.com/devondragon/ccmagic/archive/main.tar.gz | \
tar -xz -C .claude/commands --strip-components=1
# Or using wget
wget -qO- https://github.com/devondragon/ccmagic/archive/main.tar.gz | \
tar -xz -C .claude/commands --strip-components=1
# Optional: Track commands in your project's git
git add .claude/commands/
git commit -m "Add CCMagic commands to project"
# Or ignore them if you prefer team members to install separately
echo ".claude/commands/" >> .gitignore
```
**Note:** Project-local commands take precedence over global commands. This allows teams to:
- Pin specific CCMagic versions per project
- Customize commands for project needs
- Ensure all team members use the same command versions
### Your First Command
Initialize a new project with the CCMagic context system:
```
/ccmagic:init # Full setup with epics, features, knowledge base
/ccmagic:init --light # Minimal setup for simple projects
```
This creates a project management structure in your repository's `context/` directory.
## 📋 Available Commands
### Project Setup & Planning
| Command | Description | Example |
| --------------------- | -------------------------------------------------- | ---------------------------- |
| `/ccmagic:init` | Initialize CCMagic context (`--light` for minimal) | `/ccmagic:init --light` |
| `/ccmagic:plan` | Interactive planning with EnterPlanMode support | `/ccmagic:plan saas-app` |
| `/ccmagic:quick-start`| Fast-track feature setup | `/ccmagic:quick-start auth` |
| `/ccmagic:map-codebase`| Analyze existing codebase and document patterns | `/ccmagic:map-codebase` |
| `/ccmagic:settings` | Configure CCMagic preferences | `/ccmagic:settings` |
| `/ccmagic:help` | Get help with CCMagic commands | `/ccmagic:help` |
| `/ccmagic:doctor` | Diagnose setup issues and validate installation | `/ccmagic:doctor` |
### Task Management
| Command | Description | Example |
| -------------------------- | ------------------------------------------ | ----------------------------------- |
| `/ccmagic:create-features` | Create new features for an epic | `/ccmagic:create-features epic-001` |
| `/ccmagic:discuss-feature` | Gather implementation context before tasks | `/ccmagic:discuss-feature` |
| `/ccmagic:create-tasks` | Break down features into tasks | `/ccmagic:create-tasks` |
| `/ccmagic:start-task` | Start working on a specific task | `/ccmagic:start-task 001-01-003` |
| `/ccmagic:current-task` | View current active task | `/ccmagic:current-task` |
| `/ccmagic:complete-task` | Mark task as completed | `/ccmagic:complete-task 001-01-003` |
| `/ccmagic:verify` | Interactive verification of acceptance criteria | `/ccmagic:verify` |
| `/ccmagic:checkpoint` | Save current progress | `/ccmagic:checkpoint` |
### Features & Epics
| Command | Description | Example |
| -------------------------- | ---------------------------------- | -------------------------------- |
| `/ccmagic:current-feature` | View current feature status | `/ccmagic:current-feature` |
| `/ccmagic:create-spike` | Create research/investigation task | `/ccmagic:create-spike` |
| `/ccmagic:start-spike` | Begin working on a spike | `/ccmagic:start-spike spike-001` |
### Project Status & Documentation
| Command | Description | Example |
| ------------------------ | ---------------------------------------- | ---------------------------------- |
| `/ccmagic:status` | Quick project status check (uses haiku) | `/ccmagic:status` |
| `/ccmagic:progress` | Check progress and route to next action | `/ccmagic:progress` |
| `/ccmagic:daily-standup` | Generate standup report from git history | `/ccmagic:daily-standup` |
| `/ccmagic:handoff` | Create detailed handoff notes | `/ccmagic:handoff` |
| `/ccmagic:add-backlog` | Add items to project backlog | `/ccmagic:add-backlog` |
| `/ccmagic:blockers` | Surface and track blockers | `/ccmagic:blockers` |
| `/ccmagic:research` | Deep iterative research with sources | `/ccmagic:research JWT vs sessions`|
### Context Management
| Command | Description | Example |
| ----------------------- | ----------------------------------- | ----------------------- |
| `/ccmagic:context-save` | Save current context state | `/ccmagic:context-save` |
| `/ccmagic:context-load` | Load saved context state | `/ccmagic:context-load` |
| `/ccmagic:resume` | Resume work from previous session | `/ccmagic:resume` |
### Development Workflow
| Command | Description | Example |
| ------------------------ | --------------------------------------------- | ---------------------------------- |
| `/ccmagic:quick` | Execute ad-hoc task without feature overhead | `/ccmagic:quick fix typo in login` |
| `/ccmagic:test` | Run project tests | `/ccmagic:test` |
| `/ccmagic:validate` | Validate code (parallel checks) | `/ccmagic:validate` |
| `/ccmagic:review` | Code review with parallel exploration | `/ccmagic:review` |
| `/ccmagic:codex-review` | Codex CLI review + Claude triage and fix plan | `/ccmagic:codex-review branch` |
| `/ccmagic:debug` | Systematic debugging with persistent state | `/ccmagic:debug login issue` |
| `/ccmagic:analyze-impact`| Analyze dependencies and blast radius | `/ccmagic:analyze-impact src/auth` |
### Git Integration
| Command | Description | Example |
| -------------------- | ------------------------------------------------ | -------------------- |
| `/ccmagic:push` | Smart commit (logical groups) and push | `/ccmagic:push` |
| `/ccmagic:pr` | Create pull request | `/ccmagic:pr` |
| `/ccmagic:pr-feedback`| Review PR comments and plan fixes | `/ccmagic:pr-feedback`|
| `/ccmagic:merge` | Merge changes | `/ccmagic:merge` |
| `/ccmagic:sync` | Sync with remote repository | `/ccmagic:sync` |
## ⚡ Claude Code Integration
CCMagic leverages Claude Code's latest features for maximum efficiency:
### Parallel Subagents
Commands like `/review` and `/analyze-impact` use the **Task tool with Explore agents** to analyze code in parallel:
```
# /review launches 3 parallel agents:
Agent 1: Code quality analysis
Agent 2: Security & performance review
Agent 3: Architecture & integration check
```
### Real-time Progress with TodoWrite
Commands populate Claude Code's native todo UI for visibility:
- `/start-task` creates checklist from acceptance criteria
- `/plan` shows next steps after planning
- Progress updates in real-time as you work
### Parallel Execution
Commands like `/validate` run independent checks simultaneously:
```
# These run IN PARALLEL (single message, multiple Bash calls):
- Linting
- Type checking
- Format checking
- Security scanning
# Then SEQUENTIAL (depends on above):
- Tests
- Build
```
### Model Tiering
Commands use appropriate models for their complexity:
- **haiku**: Fast operations (`/status`, `/daily-standup`, `/blockers`)
- **sonnet**: Standard operations (`/review`, `/validate`, `/start-task`)
- **opus**: Complex reasoning (`/plan`, `/create-features`, `/create-tasks`, `/research`)
### Optional MCP Tool Integration
Commands integrate with external MCP tools when available, with graceful fallback:
| Tool | Purpose | Fallback |
|------|---------|----------|
| `mcp__pal__codereview` | Expert code review | Explore agents |
| `mcp__pal__analyze` | Deep analysis | Standard analysis |
| `mcp__pal__planner` | Planning assistance | Task tool with Plan agent |
**All commands work fully without MCP tools** - they're optional enhancements.
### Optional CLI Tool Integration
Some commands integrate with external CLI tools for enhanced capabilities:
| Tool | Command | Purpose | Fallback |
|------|---------|---------|----------|
| Codex CLI | `/ccmagic:codex-review` | OpenAI's Codex for code review | `/ccmagic:review` |
Install Codex with `npm install -g @openai/codex`. Commands gracefully fall back when tools aren't installed.
## 🏗️ CCMagic Context System
CCMagic creates a hierarchical project organization that scales from simple to complex projects:
### Directory Structure
```
your-project/
├── context/ # All project context
│ ├── project.md # Project overview & tech stack
│ ├── conventions.md # Coding standards
│ ├── working-state.md # Current status
│ ├── backlog.md # Ideas & tech debt
│ ├── epics/ # Major initiatives
│ │ └── epic-001-mvp.md
│ ├── features/ # Feature implementations
│ │ └── epic-001-f01-core/
│ │ ├── overview.md
│ │ ├── working-state.md
│ │ └── tasks/
│ │ ├── todo/
│ │ ├── current/
│ │ └── completed/
│ ├── spikes/ # Research tasks
│ │ ├── todo/
│ │ ├── current/
│ │ └── completed/
│ ├── knowledge/ # Technical docs & research
│ │ ├── architecture.md
│ │ ├── data-model.md
│ │ ├── api-contracts.md
│ │ └── research-*.md # Research findings from /research
│ └── sessions/ # Work history
│ └── handoffs/
└── CLAUDE.md # AI assistant instructions
```
### Hierarchy Explained
- **Epics**: High-level feature groups (e.g., Authentication, Payments, Analytics)
- **Features**: Specific implementations within epics (e.g., Login, Registration, Password Reset)
- **Tasks**: Individual work items within features
- **Spikes**: One-off research or investigation tasks
### ID Convention
Tasks follow the format `XXX-YY-ZZZ-description`:
- `XXX`: Epic number (001)
- `YY`: Feature number (01)
- `ZZZ`: Task number (003)
- Example: `001-01-003-add-login-form`
## 🎯 Use Cases
### Solo Developer
Start simple with minimal setup:
```
/ccmagic:init --light # Minimal structure for simple projects
/ccmagic:plan my-feature
/ccmagic:start-task
# Work on tasks
/ccmagic:checkpoint
/ccmagic:complete-task
```
### Team Collaboration
Enable smooth handoffs and parallel work:
```
/ccmagic:handoff # Developer A creates handoff
/ccmagic:context-load # Developer B picks up work
/ccmagic:status # Check team progress
/ccmagic:review # Code review workflow
```
### Complex Projects
Manage multiple epics and features:
```
/ccmagic:plan enterprise-app
/ccmagic:create-features epic-001
/ccmagic:create-tasks
/ccmagic:start-task 001-02-005
```
## 💡 Best Practices
### For Maximum Productivity
1. **Initialize First**: Always run `/ccmagic:init` in new projects
2. **Regular Checkpoints**: Use `/ccmagic:checkpoint` to save progress frequently
3. **Clear Handoffs**: Create handoffs when switching contexts or developers
4. **Update Working State**: Keep `context/working-state.md` current
5. **Use Backlog**: Capture ideas without breaking flow with `/ccmagic:add-backlog`
### Workflow Tips
- Start with a single epic (`001-mvp`) and expand as needed
- Complete one task at a time to avoid context switching
- Use spikes for research that doesn't fit into features
- Document decisions in working-state files
- Review `/ccmagic:status` at the start of each session
## 🛠️ Creating Custom Commands
Add new commands by creating `.md` files in the repository root:
### Example Command Structure
```markdown
---
description: Brief description of the command
argument-hint: expected arguments
allowed-tools: Read(*), Bash(git:*), Task(*), TodoWrite(*)
model: sonnet
---
# Command Title
Your command prompt here using:
- $ARGUMENTS for dynamic values
- Markdown for formatting
```
### Available Tools
Commands can request access to:
**Core Tools:**
- `Write(*)` - File writing
- `Read(*)` - File reading
- `Bash(git:*)` - Git commands (use `Bash(*)` for all shell access)
- `Glob(*)` - File pattern matching
- `Grep(*)` - Content searching
- `LS(*)` - Directory listing
**Claude Code Features:**
- `Task(*)` - Spawn subagents (Explore, Plan, general-purpose)
- `TodoWrite(*)` - Real-time progress tracking in UI
- `EnterPlanMode(*)` - Interactive planning workflow
- `AskUserQuestion(*)` - Multi-choice user prompts
**Optional MCP Tools (graceful fallback if unavailable):**
- `mcp__pal__codereview(*)` - Expert code review
- `mcp__pal__thinkdeep(*)` - Deep analysis
- `mcp__pal__analyze(*)` - Comprehensive analysis
### Model Selection
Choose appropriate models in frontmatter (aliases auto-update to latest versions):
```yaml
model: haiku # Fast, simple operations
model: sonnet # Standard operations (default)
model: opus # Complex reasoning
```
### Parallel Execution Pattern
For commands that run independent operations:
```markdown
Run these checks IN PARALLEL using multiple Bash tool calls in a single message:
- Check 1: [command]
- Check 2: [command]
- Check 3: [command]
```
## 📚 Documentation
Detailed documentation available in the `/docs` directory:
- [Getting Started Guide](docs/getting-started.markdown)
- [Team Collaboration Guide](docs/claude-code-team-guide.markdown)
- [Claude Code Quickstart](docs/claude-code-quickstart.markdown)
- [Directory Structure Reference](docs/directory-structure.markdown)
- [Context Systems Reference](docs/context-systems-reference.markdown)
## 🤝 Contributing
We welcome contributions! To add new commands:
1. Fork the repository
2. Create a new `.md` file for your command
3. Test thoroughly with Claude Code
4. Update this README with your command
5. Submit a pull request
### Contribution Guidelines
- Follow existing command patterns
- Include comprehensive frontmatter
- Document complex workflows
- Test with various project types
- Update relevant documentation
## 📝 License
Apache 2.0 License - See [LICENSE](LICENSE) file for details
## 🔗 Links
- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
- [Report Issues](https://github.com/devondragon/ccmagic/issues)
- [Feature Requests](https://github.com/devondragon/ccmagic/discussions)
## 🎉 Why CCMagic?
CCMagic transforms Claude Code from a coding assistant into a complete project management system. It provides:
- **Structured Organization**: Hierarchical task management that scales from solo to enterprise
- **Context Preservation**: Never lose track of what you were working on
- **Team Collaboration**: Smooth handoffs, blocker tracking, and clear communication
- **Claude Code Native**: Uses subagents, TodoWrite, and parallel execution for efficiency
- **Flexible Setup**: Light mode for simple projects, full mode for complex ones
- **Optional Enhancements**: PAL MCP tools enhance when available, graceful fallback otherwise
- **Real-time Visibility**: TodoWrite integration shows progress in Claude Code's UI
Start using CCMagic today and experience a new level of development productivity with Claude Code!
---
*Built by developers, for developers who want to maintain their sanity while building amazing things.*