PrePilot Server

---

✨ 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) 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

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.

🔌 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.

🧩 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 and the 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 for the full guide.

📜 License

This project is licensed under the MIT License — see 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
• 📦 Production app: app.prepilot-system-agency.space
• 💬 Discord: [coming soon]
• 🐦 Twitter / X: @imMamdouhaboammar

---