# PrePilot — AI Marketing Agency Suite

<div align="center">

**MCP-first, multi-agent orchestration platform for marketing agencies.**

*Turn intent into a deterministic skill composition plan — across 1,000+ marketing skills, in any language, for any workflow.*

[**Website**](https://prepilot-system-agency.space) · [**Live Demo**](https://app.prepilot-system-agency.space) · [**Documentation**](./docs/ARCHITECTURE.md)

</div>

---

## ✨ What is PrePilot?

PrePilot is an **open-source marketing agency in a box**. It exposes a deterministic orchestration layer that maps free-form marketing intent (Arabic, English, mixed) to a runnable plan — composed from a catalog of **1,000+ production-tested skills**, wired through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) so any AI client (Claude Code, Cursor, Custom GPT, Codex, Gemini CLI) can plug in and ship campaigns end-to-end.

```
┌─────────────────────────────────────────────────────────────────┐
│  AI Client (Claude Code · Cursor · Custom GPT · Codex · Gemini) │
└──────────────────────────────┬──────────────────────────────────┘
                               │  MCP / SSE / Custom GPT Actions
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│  PrePilot MCP Server                                             │
│  ─────────────────────────────────────────────────────────────── │
│   • Intent router    →  13 canonical workflows (paid, SEO, ...) │
│   • Skill catalog    →  1,040 skills mapped to taxonomy         │
│   • Swarm compiler   →  agents.py + manifest.json + workflow    │
│   • Engagement engine→  role → artifact → role → artifact ...   │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│  Compiled Agent Runtime                                          │
│   • 1,700+ pre-built agents  (worker · coordinator · critic)     │
│   • 4 topology modes       (pipeline · parallel · hierarchical) │
│   • Append-only memory     (rules · episodes · agency data)     │
└──────────────────────────────────────────────────────────────────┘
```

## 🚀 Quick Start

```bash
git clone https://github.com/imMamdouhaboammar/PrePilot-oss.git
cd PrePilot-oss
pip install -e ".[dev]"

# Start the sample MCP server
python examples/mcp-server/server.py

# Wire it into Claude Code
claude mcp add prepilot-sample -- python examples/mcp-server/server.py
```

Then in your AI client:

```
You: Launch a paid Meta campaign for my DTC skincare brand in Saudi.
PrePilot: I'll run the `launch_paid_ad_campaign` workflow.
           [step 1/6] audience research (geo-fundamentals + market-segments)
           [step 2/6] brand voice capture (brand-voice-guide)
           ...
           [step 6/6] ad creative generation (ad-copy + ad-creative-brief)
           ✓ Plan ready. Estimated cost: SAR 12,000.
```

## 🎯 Who is PrePilot for?

| You are... | PrePilot helps you... |
|---|---|
| **Marketing agency owner** | Run 10× the campaigns with the same headcount |
| **Brand marketer** | Get a senior strategist + executor pair on demand |
| **Marketing ops engineer** | Stop building one-off campaign scripts — compose from tested skills |
| **Indie hacker** | Ship a full GTM playbook in an afternoon |
| **AI client developer** | Plug into 1,000+ production skills without writing them yourself |

## 📦 What's in this repo

```
PrePilot-oss/
├── README.md                       ← you are here
├── LICENSE                         ← MIT
├── CONTRIBUTING.md                 ← how to add your skill
├── CODE_OF_CONDUCT.md
├── docs/
│   ├── ARCHITECTURE.md             ← how PrePilot works end-to-end
│   ├── MCP_INTEGRATION.md          ← wire into Claude / Cursor / GPT
│   ├── SKILLS_GUIDE.md             ← anatomy of a skill
│   └── ROADMAP.md                  ← what's next
├── examples/
│   ├── mcp-server/                 ← runnable MCP server skeleton
│   ├── chatkit-widgets/            ← sample ChatKit widgets for GPT apps
│   └── skills/                     ← 25 sample skills (canonical taxonomy)
├── src/
│   └── compiled_agents/            ← 25 sample agents (worker + coordinator)
├── templates/
│   ├── SKILL.template.md
│   ├── WORKFLOW.template.md
│   ├── PROMPTS.template.md
│   ├── skill.yaml
│   ├── input.schema.json
│   └── output.schema.json
├── assets/
│   └── (logos, diagrams)
├── pyproject.toml
└── .github/                        ← issue templates + CI workflows
```

## 🧠 Architecture in 30 seconds

1. **User intent arrives** ("launch paid Meta campaign in Saudi")
2. **Intent router classifies** it: `language=en`, `workstream=paid_ad`, `complexity=multi_step`
3. **System layer recommends** the matching workflow (`launch_paid_ad_campaign`)
4. **Workflow materializes** into ordered steps with skill IDs injected
5. **Each skill compiles** into an `agent.py` + `manifest.json` (deterministic codegen, no LLM in the loop)
6. **Swarm executes** in the chosen topology (pipeline / parallel / hierarchical / DAG)
7. **Engagement engine validates** each artifact contract before handoff to the next role
8. **Memory accumulates** — episodic archive, rule inbox, agency decisions

For the deep dive, see [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md).

## 🔌 MCP Integration

PrePilot is **MCP-native**. Any MCP-compatible client (Claude Code, Cursor, Codex, Gemini CLI, ChatGPT with MCP support, etc.) can plug in directly.

| Transport | Use when |
|---|---|
| **stdio** | Local AI client (Claude Code on your machine) — recommended |
| **SSE/HTTP** | Remote AI client (Cloud Run deploy, ChatGPT widget, public MCP gateway) |
| **Custom GPT Actions** | OpenAI Apps SDK with the OpenAPI schema exported from this repo |

Full wiring instructions in [`docs/MCP_INTEGRATION.md`](./docs/MCP_INTEGRATION.md).

## 🧩 Skills Catalog (this repo ships 25 of 1,040)

The full catalog lives in the private production deployment. **This OSS repo ships 25 representative skills** spanning every major marketing domain — enough to compose any workflow and to demonstrate the skill authoring pattern.

| Domain | Sample skill |
|---|---|
| Paid acquisition | `ad-copy`, `ad-creative-brief`, `landing-page-architect` |
| SEO / AEO / GEO | `seo-technical`, `geo-fundamentals`, `programmatic-seo-content` |
| Brand & voice | `brand-voice-guide`, `value-prop-statements`, `ambassador-program` |
| Content & media | `content-strategy`, `content-ops`, `podcast-ops` |
| Email & lifecycle | `email-nurture-sequence` |
| Analytics & growth | `ab-test-analysis`, `linkedin-engager-analytics`, `cash-flow-forecast` |
| Strategy & ops | `competitor-analysis`, `market-segments`, `fulfillment-sop`, `compliance-checklist` |
| Sales & conversion | `sales-script`, `growth-loops` |
| Copywriting | `copywriting` |
| Chat & messaging | `telegram-mini-app` |

Want to add your own skill? See [`CONTRIBUTING.md`](./CONTRIBUTING.md) and the [`templates/`](./templates/) folder.

## 🤝 Contributing

We welcome:
- 🆕 **New skills** — drop a folder under `examples/skills/<your-skill-id>/` with `SKILL.md`, `skill.yaml`, `input/output.schema.json`
- 🐛 **Bug reports** — open an issue
- 📖 **Docs improvements** — PRs welcome
- 🌍 **Translations** — Arabic, Spanish, French, German, etc.

See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the full guide.

## 📜 License

This project is licensed under the **MIT License** — see [`LICENSE`](./LICENSE).

## 🔐 Production vs OSS

The OSS release is a **curated, public-safe subset** of the full production system. The production deployment includes:

- 1,040 production skills (vs 25 here)
- 1,700+ compiled agents (vs 25 here)
- Proprietary orchestration SOPs (paid-campaign-launch, content-program, brand-refresh, ppc-audit)
- Live ad-platform integrations (Meta, GA4, Google Ads)
- Customer-tuned agency memory (brand voices, campaign histories, decisions)
- Cost & pacing optimization engines

The OSS version is designed to be **fully runnable** and to demonstrate the architecture — without exposing the proprietary IP that powers the production SaaS.

## 🌐 Links

- 🌐 **Website**: [prepilot-system-agency.space](https://prepilot-system-agency.space)
- 📦 **Production app**: [app.prepilot-system-agency.space](https://app.prepilot-system-agency.space)
- 💬 **Discord**: [coming soon]
- 🐦 **Twitter / X**: [@imMamdouhaboammar](https://github.com/imMamdouhaboammar)

---

<div align="center">

Built with ❤️ in Cairo · Shipped to the world

</div>