Metadata-Version: 2.4
Name: mmo
Version: 0.5.0
Summary: A powerful AI orchestrator and skill system for Antigravity, Claude Code, GitHub Copilot, and more. Featuring 60+ specialized domain expert skills, disciplined development workflows, and RTK token optimization.
Author-email: Plamen Ivanov <paco.iwanow@gmail.com>
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Description-Content-Type: text/markdown

# Mega-Mind Skills System

> **A unified superpowers + virtual company skill set for AI coding assistants**

This is a comprehensive skill-based workflow system that combines the disciplined development workflows of [Superpowers](https://github.com/obra/superpowers) with the domain expertise of [Virtual Company](https://github.com/k1lgor/virtual-company) and [Everything-Claude-Code](https://github.com/affaan-m/everything-claude-code). It provides structured, reliable behavior for AI coding assistants across the entire software development lifecycle.

**Compatible with:** Antigravity · GitHub Copilot (VS Code) · Claude Code · Cursor · OpenCode · Codex · and any AI tool that supports the [Agent Skills open standard](https://agentskills.io)

## Overview

Mega-Mind brings together **59 skills** organized into categories:

### The Mega-Mind Orchestrator (1 skill)

The master controller that routes requests and coordinates skill chains:

- `mega-mind` - Primary entry point via `/mega-mind` command

### Core Workflow Skills (12 skills)

Structured development discipline that ensures quality at every step:

- `brainstorming` - Explore approaches before committing
- `writing-plans` - Create detailed implementation plans
- `executing-plans` - Disciplined execution with tracking
- `single-flow-task-execution` - Sequential task decomposition
- `test-driven-development` - Write tests first, implement second
- `systematic-debugging` - Root cause analysis methodology
- `requesting-code-review` - Structured review requests
- `receiving-code-review` - Handle feedback systematically
- `verification-before-completion` - Prove it works before done
- `finishing-a-development-branch` - Clean branch management
- `using-git-worktrees` - Parallel development workflows
- `writing-skills` - Create new custom skills

### Domain Expert Skills (32 skills)

Specialized expertise for specific technical domains:

- **Architecture**: tech-lead, frontend-architect, backend-architect, infra-architect, api-designer
- **Development**: code-polisher, migration-upgrader, mobile-architect, legacy-archaeologist, python-patterns
- **Testing**: test-genius, e2e-test-specialist, bug-hunter, eval-harness
- **DevOps**: ci-config-helper, docker-expert, k8s-orchestrator, observability-specialist, deployment-patterns
- **Data**: data-engineer, data-analyst, ml-engineer, search-vector-architect, database-migrations, regex-vs-llm-structured-text
- **Security**: security-reviewer
- **Performance**: performance-profiler
- **Documentation**: doc-writer
- **UX**: ux-designer
- **Product**: product-manager, workflow-orchestrator
- **Meta**: skill-generator

### Meta & Learning Skills (12 skills)

Advanced patterns for efficiency and continuous improvement:

- `continuous-learning-v2` - Instinct extraction and evolution (The Learning Loop)
- `search-first` - Mandatory research and library check before coding
- `autonomous-loops` - Multi-step AI pipeline patterns without intervention
- `skill-stocktake` - Quality audit and library maintenance
- `cost-aware-llm-pipeline` - Model routing and token budget tracking
- `verification-loop` - 6-phase continuous verification pipeline
- `iterative-retrieval` - Progressive context refinement for subagents
- `strategic-compact` - Logical context window management
- `content-hash-cache-pattern` - SHA-256 caching for file processing
- `multi-plan` - Collaborative multiple-model planning
- `multi-execute` - Orchestrated multi-model execution and audit
- `plankton-code-quality` - Write-time formatting and linting enforcement

### Token Optimization & Context (2 skills)

Reduce LLM Token consumption and manage context limits:

- `rtk` - CLI proxy for 60-90% token savings on common dev commands
- `context-optimizer` - Context offloading and session continuity

---

## Quick Start

### 1. Install the CLI

```bash
# pip
pip install mmo

# pipx (recommended — isolated, globally available)
pipx install mmo

# uv
uv tool install mmo

# Or run directly without installation
uvx mmo
```

### 2. Initialize skills in your project

```bash
# From your project root
cd /path/to/your/project

# Standard install (Antigravity, Cursor, and other standard tools)
mmo init

# Also install for Claude Code (CLI)
mmo init --claude

# Also install for GitHub Copilot (VS Code)
mmo init --copilot

# Overwrite an existing installation
mmo init --force
mmo init --copilot --claude --force
```

The `--claude` flag adds:

- `CLAUDE.md` — project rules and workflows (mirrors `AGENTS.md`)
- `.claude/skills/` — all 59 skills in the Agent Skills standard directory

The `--copilot` flag adds a `.github/` directory with:

- `copilot-instructions.md` — global instructions loaded automatically
- `skills/<name>/SKILL.md` — all 59 skills available as `/` slash commands
- `agents/<name>.agent.md` — custom agent personas for VS Code

> 📖 For full details see [USAGE.md](./USAGE.md)

### 3. Verify the installation

Once initialized, use the `/verify` command (triggered by the `verification-before-completion` skill) or run the `verification-loop` to ensure all components are correctly installed and functional.

> 📖 For full installation details see [USAGE.md](./USAGE.md)

---

## Using Mega-Mind

### The `/mega-mind` Command

The `/mega-mind` command is your primary entry point to the skill system. It acts as an intelligent orchestrator that:

1. **Analyzes** your request to understand intent
2. **Routes** to the appropriate skill(s)
3. **Coordinates** skill chains for complex tasks
4. **Tracks** progress throughout

### Available Commands

```
/mega-mind status             - Show current session state
/mega-mind skills             - List all available skills
/mega-mind workflows          - List available workflows
/mega-mind route <request>    - Analyze and route a request
/mega-mind execute <workflow> - Execute a named workflow
/mega-mind help               - Show help message
```

### Direct Skill Commands

| Command       | Skill                          | Purpose                            |
| ------------- | ------------------------------ | ---------------------------------- |
| `/brainstorm` | brainstorming                  | Explore approaches before deciding |
| `/plan`       | writing-plans                  | Create implementation plan         |
| `/execute`    | executing-plans                | Execute plan with tracking         |
| `/debug`      | systematic-debugging           | Debug systematically               |
| `/review`     | requesting-code-review         | Request code review                |
| `/ship`       | finishing-a-development-branch | Deploy to production               |
| `/tdd`        | test-driven-development        | Test-first development             |
| `/verify`     | verification-before-completion | Verify before marking done         |

### Example Usage

```
User: /mega-mind I need to add user authentication with OAuth

🧠 Mega-Mind Orchestration
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 Request Analyzed: New feature - User Authentication with OAuth

🔄 Routed to skill chain:
   1. tech-lead                        → Define architecture
   2. brainstorming                    → Explore OAuth providers
   3. api-designer                     → Design auth API
   4. writing-plans                    → Create implementation plan
   5. test-driven-development          → Write auth tests
   6. backend-architect                → Implement auth service
   7. frontend-architect               → Implement login UI
   8. security-reviewer                → Security audit
   9. verification-before-completion   → Verify

📍 Starting with: tech-lead
```

---

## File Structure

```
mega-mind-skills/
├── README.md                    # Main documentation (this file)
├── USAGE.md                     # Installation guide
├── COMPLETE_REFERENCE.md        # Detailed reference
├── quick-install.sh             # Simple copy installer (legacy)
│
└── .agent/
    ├── AGENTS.md                # Master contract and rules
    ├── hooks/
    │   └── hooks.json           # context-mode hooks registry
    ├── instincts/               # Learned patterns & observations
    ├── skills/
    │   ├── mega-mind/           # 🧠 Master orchestrator
    │   │
    │   ├── # Core Workflow Skills
    │   ├── brainstorming/
    │   ├── writing-plans/
    │   ├── executing-plans/
    │   ├── single-flow-task-execution/
    │   ├── test-driven-development/
    │   ├── systematic-debugging/
    │   ├── requesting-code-review/
    │   ├── receiving-code-review/
    │   ├── verification-before-completion/
    │   ├── finishing-a-development-branch/
    │   ├── using-git-worktrees/
    │   └── writing-skills/
    │   │
    │   ├── # Domain Expert Skills
    │   ├── tech-lead/
    │   ├── frontend-architect/
    │   ├── backend-architect/
    │   ├── infra-architect/
    │   ├── api-designer/
    │   ├── code-polisher/
    │   ├── migration-upgrader/
    │   ├── mobile-architect/
    │   ├── legacy-archaeologist/
    │   ├── python-patterns/
    │   ├── test-genius/
    │   ├── e2e-test-specialist/
    │   ├── bug-hunter/
    │   ├── eval-harness/
    │   ├── ci-config-helper/
    │   ├── docker-expert/
    │   ├── k8s-orchestrator/
    │   ├── observability-specialist/
    │   ├── deployment-patterns/
    │   ├── data-engineer/
    │   ├── data-analyst/
    │   ├── ml-engineer/
    │   ├── search-vector-architect/
    │   ├── database-migrations/
    │   ├── regex-vs-llm-structured-text/
    │   ├── security-reviewer/
    │   ├── performance-profiler/
    │   ├── doc-writer/
    │   ├── ux-designer/
    │   ├── product-manager/
    │   ├── workflow-orchestrator/
    │   └── skill-generator/
    │   │
    │   ├── # Meta & Learning Skills
    │   ├── continuous-learning-v2/
    │   ├── search-first/
    │   ├── autonomous-loops/
    │   ├── skill-stocktake/
    │   ├── cost-aware-llm-pipeline/
    │   ├── verification-loop/
    │   ├── iterative-retrieval/
    │   ├── strategic-compact/
    │   ├── content-hash-cache-pattern/
    │   ├── multi-plan/
    │   ├── multi-execute/
    │   └── plankton-code-quality/
    │   │
    │   └── # Token Optimization & Context
    │       ├── rtk/
    │       └── context-optimizer/
    │
    ├── workflows/
    │   ├── brainstorm.md
    │   ├── debug.md
    │   ├── execute-plan.md
    │   ├── high-complexity-dev.md
    │   ├── review.md
    │   ├── ship.md
    │   └── write-plan.md
    │
    ├── agents/
    │   ├── architect.md
    │   ├── code-reviewer.md
    │   ├── planner.md
    │   ├── qa-engineer.md
    │   ├── security-reviewer.md
    │   └── tech-lead.md
    │
    └── tests/
        └── run-tests.sh
```

---

## Skill Routing Matrix

The `mega-mind` orchestrator automatically routes requests to appropriate skills:

| Request Type  | Primary Skill           | Secondary Skills                |
| ------------- | ----------------------- | ------------------------------- |
| New feature   | tech-lead               | brainstorming, writing-plans    |
| Bug fix       | systematic-debugging    | bug-hunter                      |
| Code quality  | code-polisher           | -                               |
| Performance   | performance-profiler    | -                               |
| Security      | security-reviewer       | -                               |
| Testing       | test-driven-development | test-genius                     |
| Documentation | doc-writer              | -                               |
| API design    | api-designer            | backend-architect               |
| Frontend      | frontend-architect      | ux-designer                     |
| Backend       | backend-architect       | api-designer                    |
| DevOps        | infra-architect         | docker-expert, k8s-orchestrator |
| Data          | data-engineer           | data-analyst                    |
| ML/AI         | ml-engineer             | -                               |
| Mobile        | mobile-architect        | -                               |
| Legacy code   | legacy-archaeologist    | -                               |

---

## Workflows

### Standard Development Chain (The Z-Pattern)

```
search-first → tech-lead → brainstorming → writing-plans → test-driven-development →
executing-plans → verification-loop → requesting-code-review →
finishing-a-development-branch → continuous-learning-v2
```

### High-Complexity Chain (Phase 3 Orchestration)

```
search-first → architect → multi-plan → [Approval] → multi-execute →
verification-loop → security-reviewer → finishing-a-development-branch
```

### Autonomous Loop Chain

```
writing-plans → autonomous-loops → [Loop Execution] → verification-loop →
continuous-learning-v2
```

### Bug Fix

```
systematic-debugging → bug-hunter → test-driven-development →
verification-loop → finishing-a-development-branch → continuous-learning-v2
```

### Code Improvement

```
plankton-code-quality → code-polisher → test-driven-development → verification-loop
```

---

## Key Concepts

### Task Tracking

All tasks are tracked in `<project-root>/docs/plans/task.md`:

| Task ID | Description  | Status  | Priority | Dependencies |
| ------- | ------------ | ------- | -------- | ------------ |
| 1       | Example task | pending | high     | -            |

Status values: `pending`, `in_progress`, `completed`, `blocked`

### Verification Before Completion

Never mark a task as complete without:

1. Running tests
2. Running linting
3. Building successfully
4. Manual verification
5. Checking for regressions

### Execution Model

1. Session loads `.agent/AGENTS.md` rules
2. `/mega-mind` analyzes and routes requests
3. Design work flows through brainstorming → planning → execution
4. All work tracked in task tracker
5. Nothing marked done without verification

### RTK Token Optimization

When [RTK](https://github.com/rtk-ai/rtk) is installed, CLI commands are automatically optimized:

| Original     | RTK-Optimized    | Savings |
| ------------ | ---------------- | ------- |
| `git log`    | `rtk git log`    | 85%     |
| `cargo test` | `rtk cargo test` | 90%     |
| `npm test`   | `rtk npm test`   | 90%     |
| `pytest`     | `rtk pytest`     | 90%     |

Install RTK:

```bash
cargo install rtk
# or
curl -sSL https://github.com/rtk-ai/rtk/releases/latest/download/rtk-$(uname -s)-$(uname -m) -o /usr/local/bin/rtk
chmod +x /usr/local/bin/rtk
```

---

## Installation

See [USAGE.md](./USAGE.md) for the full installation guide.

### CLI Reference

```bash
# Install skills into current directory (Antigravity / Claude / Cursor / standard)
mmo init

# Also install for OpenCode
mmo init --opencode

# Also install for Codex
mmo init --codex

# Install into a specific path
mmo init /path/to/project
mmo init /path/to/project --copilot

# Overwrite existing installation
mmo init --force
mmo init --copilot --claude --opencode --codex --force

# Show CLI version
mmo --version
```

### Validate Installation

Use the internal `/verify` command within your AI assistant to run the verification protocol.

Tests verify:

- Core workflow skills existence
- Domain expert skills existence
- Workflows existence
- Agent profiles existence
- AGENTS.md validation
- Skill frontmatter validation

---

## Contributing

To add new skills:

1. Create a new directory in `.agent/skills/`
2. Add a `SKILL.md` file with proper frontmatter:
   ```markdown
   ---
   name: skill-name
   description: What this skill does
   triggers:
     - "/trigger"
     - "keyword"
   ---
   ```
3. Include instructions and examples
4. Run tests to verify

---

## Credits

This project combines and adapts:

- [Superpowers](https://github.com/obra/superpowers) by obra - Core workflow philosophy
- [antigravity-superpowers](https://github.com/skainguyen1412/antigravity-superpowers) by skainguyen1412 - Antigravity adaptation
- [virtual-company](https://github.com/k1lgor/virtual-company) by k1lgor - Domain expertise skills
- [Everything-Claude-Code](https://github.com/affaan-m/everything-claude-code) by affaan-m - Claude Code adaptation
- [RTK](https://github.com/rtk-ai/rtk) - Token optimization CLI

---

## License

MIT License - Free to use and modify.
