marketing-spec-kit

Specification Toolkit for Marketing Operations - Transform marketing chaos into structured, AI-driven workflows.

🌟 What is marketing-spec-kit?

A Spec-Driven Toolkit that enables marketing teams to:

✅ Define marketing operations as structured YAML specifications
✅ Validate plans, campaigns, and content against 45 business rules
✅ Execute with 10 SDM workflow commands for guided specification creation
✅ Analyze performance with AI-generated insights and optimization recommendations

v0.3.0 introduces a complete 10-command SDM (Spec-Driven Marketing) workflow system with closed-loop optimization:

Strategic Planning → Campaign Design → Content Creation → Execution → Analytics & Optimization

🚀 Quick Start

Installation

# Using pip
pip install marketing-spec-kit

# Using uv (recommended)
uv pip install marketing-spec-kit

Create Your First Marketing Plan

# Initialize a new specification
marketing_spec_kit init my-marketing-spec.yaml

# Validate the specification
marketing_spec_kit validate my-marketing-spec.yaml

Use SDM (Spec-Driven Marketing) Commands

New in v0.3.0: Complete 10-command workflow system with closed-loop optimization!

# Quick workflow (3 steps) - Simple campaign
/marketspec.discover "Grow user base in Q1 2025"
/marketspec.strategy
/marketspec.create
→ Output: marketing-spec.yaml

# Standard workflow (8 steps) - Recommended for quality
/marketspec.constitution
/marketspec.discover "Grow user base in Q1 2025"
/marketspec.clarify
/marketspec.strategy
/marketspec.checklist
/marketspec.tasks
/marketspec.analyze
/marketspec.create
→ Output: marketing-spec.yaml + quality reports

# Complete workflow (10 steps) - With feedback loop
# Phase 1: Specification (Core + Quality Gates)
/marketspec.constitution
/marketspec.discover "Q1 2025 Growth"
/marketspec.clarify
/marketspec.strategy
/marketspec.checklist
/marketspec.tasks
/marketspec.analyze
/marketspec.create

# Phase 2: Execution (AI Agent + MCP Tools)
# [AI Agent reads marketing-spec.yaml and executes campaign]

# Phase 3: Optimization (Feedback Loop)
/marketspec.review         # Analyze actual vs planned
/marketspec.optimize       # Generate optimization recommendations

See SDM Workflow Example for complete walkthrough!

📋 Core Entities (9)

marketing-spec-kit v0.3.0 manages 9 marketing entities:

Entity	Purpose	Fields	New in v0.2.0
Project	Brand identity and core values	9
Product	Feature offerings and positioning	8
MarketingPlan	Strategic marketing plan	14	✅
Campaign	Time-bound marketing activities	15	✨ Updated
Channel	Distribution platforms	9
Tool	Integration automation	7
ContentTemplate	Brand guidelines and constraints	9
Milestone	Timeline markers and events	9
Analytics	Performance analytics report	9	✅

New in v0.2.0:

MarketingPlan: Strategic planning with objectives, budget, KPIs
Analytics: AI-powered performance analysis and optimization
Campaign.plan_id: Now REQUIRED (links campaigns to plans)

🔧 CLI Commands

Command	Description
`init <file>`	Create a new marketing specification from template
`validate <file>`	Validate specification against 45 rules
`info`	Show toolkit version and statistics

🎯 SDM Command System (10)

New in v0.3.0: Complete Spec-Driven Marketing workflow with closed-loop optimization!

Core Flow (5) - Essential Workflow

#	Command	Purpose	Type	Output
1	`/marketspec.constitution`	Establish marketing principles	🔴 Core	`marketing-constitution.md`
2	`/marketspec.discover`	Discover marketing needs	🔴 Core	`*-discovery.md`
4	`/marketspec.strategy`	Plan marketing strategy	🔴 Core	`*-strategy.md`
6	`/marketspec.tasks`	Break down implementation tasks	🔴 Core	`*-tasks.md`
8	`/marketspec.create`	Generate specification YAML	🔴 Core	`marketing-spec.yaml` ⭐

Quality Gates (3) - Recommended for Quality Assurance

#	Command	Purpose	Type	Output
3	`/marketspec.clarify`	Clarify ambiguities and details	🟡 Quality Gate	`*-clarification.md`
5	`/marketspec.checklist`	Validate completeness	🟡 Quality Gate	`*-checklist.md`
7	`/marketspec.analyze`	Check consistency	🟡 Quality Gate	`consistency-report.md`

Extension (2) - Feedback Loop

#	Command	Purpose	Type	Output
9	`/marketspec.review`	Analyze actual vs. planned	🔵 Extension	`campaign-review.md`
10	`/marketspec.optimize`	Generate optimization recommendations	🔵 Extension	`optimization-plan.md`

Workflow Patterns

Quick (3 steps - Core only):

discover → strategy → create

Use when: Simple campaign, tight deadline

Standard (8 steps - Core + Quality Gates):

constitution → discover → clarify → strategy → 
checklist → tasks → analyze → create

Use when: Standard project, quality matters (Recommended)

Complete (10 steps - With Feedback Loop):

constitution → discover → clarify → strategy → 
checklist → tasks → analyze → create →
[AI Agent executes] → review → optimize

Use when: Complex campaign, continuous improvement needed

🤖 Spec-Driven Marketing Architecture

SDM's Role: Create and manage marketing specifications (YAML files)

┌─────────────────────────────────────────────────────────────┐
│  Phase 1: Specification Creation (SDM Commands 1-8)         │
│  → Output: marketing-spec.yaml                              │
└─────────────────────┬───────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────────────┐
│  Phase 2: Execution (AI Agent + MCP Tools)                  │
│  → AI Agent reads specification                             │
│  → Generates content per Campaign + ContentTemplate         │
│  → Publishes to Channels using MCP tools/APIs               │
│  → Tracks Analytics and collects data                       │
└─────────────────────┬───────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────────────┐
│  Phase 3: Analysis & Optimization (SDM Commands 9-10)       │
│  → Compares planned vs. actual results                      │
│  → Generates optimization recommendations                    │
│  → Feeds into next cycle's planning                         │
└─────────────────────────────────────────────────────────────┘
        ↓
    [Continuous Improvement Loop]

Key Insight: SDM defines WHAT (specification), AI Agents execute HOW (using MCP tools), SDM analyzes RESULTS (review & optimize).

Documentation

✅ Validation Rules (45)

marketing-spec-kit enforces 45 business rules across all entities:

Entity	Rules	Key Validations
Project	6	Brand voice, website HTTPS, target audience
Product	5	Pricing, launch date, feature list
MarketingPlan	10	Budget balance, approval, objectives, date ranges, KPIs [NEW]
Campaign	11	Budget, dates, channels, plan linkage (REQUIRED) [UPDATED]
Channel	6	Platform, constraints, tool integration
Tool	6	Credentials, rate limits, integration
ContentTemplate	5	Brand compliance, format, examples
Milestone	5	Date validity, product/campaign links
Analytics	5	Entity reference, metrics, insights, data integrity [NEW]

Performance: Validation completes in <250ms for typical specifications.

📊 Example Specification

# my-marketing-spec.yaml
project:
  name: "AwesomeApp"
  tagline: "Ship faster with AI"
  brand_voice: "Technical"
  website: "https://awesomeapp.com"
  target_audience:
    - "Developers"
    - "DevOps Engineers"
  value_propositions:
    - "10x faster deployment"
    - "AI-powered automation"

plans:
  - id: "q4-2025-growth"
    name: "Q4 2025 Growth Plan"
    project_id: "awesomeapp"
    period:
      start_date: "2025-10-01"
      end_date: "2025-12-31"
      duration_weeks: 13
    objectives:
      - "Increase brand awareness by 50%"
      - "Drive 10,000 new signups"
      - "Achieve $100K revenue"
    budget:
      total: 5000
      currency: "USD"
      allocation:
        content_creation: 2000
        paid_promotion: 2500
        tools: 300
        contingency: 200
    kpis:
      - name: "Brand Awareness"
        target: 50000
        unit: "impressions"
        measurement: "Social media + website"
        priority: "P0"
    status: "draft"
    created_at: "2025-11-15T10:00:00Z"
    updated_at: "2025-11-15T10:00:00Z"

campaigns:
  - id: "q4-awareness-launch"
    name: "Product Launch Campaign"
    goal: "awareness"
    plan_id: "q4-2025-growth"  # REQUIRED in v0.2.0
    project_id: "awesomeapp"
    target_audience: ["Developers"]
    budget: 2000
    start_date: "2025-10-01"
    end_date: "2025-10-21"
    channels: ["twitter", "dev-to", "reddit"]
    expected_kpis:
      impressions: 30000
      engagement_rate: 0.03
    status: "draft"

See examples/ for complete examples.

🏗️ Project Structure

marketing-spec-kit/
├── README.md                   # This file
├── CHANGELOG.md                # Version history
├── AGENTS.md                   # AI Agent guide (v0.3.0 SDM workflow)
├── pyproject.toml              # Python project config
├── LICENSE                     # MIT License
│
├── .metaspec/                  # MetaSpec commands (speckit development)
│   ├── commands/               # 19 MetaSpec SDS/SDD commands
│   └── README.md               # MetaSpec usage guide
│
├── memory/
│   └── constitution.md         # Core principles (v0.3.0)
│
├── specs/
│   ├── domain/
│   │   └── 001-marketing-operations-spec/
│   │       ├── spec.md         # Domain specification (v0.3.0)
│   │       ├── analysis/       # Quality analysis reports
│   │       │   ├── full-analysis.md
│   │       │   └── quick-analysis.md
│   │       └── checklists/     # Quality checklists
│   │           └── comprehensive-quality.md
│   └── toolkit/
│       └── 001-marketing-spec-kit-implementation/
│           ├── spec.md         # Toolkit specification (v0.3.0)
│           ├── plan.md         # Implementation plan
│           ├── tasks.md        # Task breakdown
│           ├── analysis/       # Quality analysis reports
│           └── checklists/     # Quality checklists
│
├── examples/
│   ├── complete-example.yaml           # Complete v0.3.0 example
│   ├── metaspec-marketing.yaml         # MetaSpec format example
│   ├── metaspec-marketing-plan.md      # Plan documentation
│   └── sdm-workflow-example.md         # SDM workflow walkthrough
│
├── templates/
│   ├── entity_templates/       # Init templates (minimal/default/full)
│   └── sdm/
│       ├── README.md           # SDM system documentation
│       └── commands/           # 10 SDM workflow commands
│
├── docs/
│   └── internal/               # Internal documentation (gitignored)
│       └── architecture-decisions-2025-11-16.md
│
└── src/marketing_spec_kit/
    ├── __init__.py             # Package exports (v0.3.0)
    ├── models.py               # 9 entities + 11 nested models
    ├── parser.py               # YAML/JSON parser
    ├── validator.py            # 45 validation rules
    ├── cli.py                  # CLI commands (init, validate, info)
    └── exceptions.py           # Custom exceptions

📚 Documentation

AGENTS.md - Complete AI Agent workflow guide
CHANGELOG.md - Version history and changes
memory/constitution.md - Core principles (v1.3.0)
specs/domain/ - Domain specification (v0.3.0)
changes/ - Evolution proposals

🤝 Contributing

This project follows Spec-Driven Development using MetaSpec:

Specify First: Define changes in specs/ before coding
Validate Early: Run validation before implementation
Document Changes: Use Evolution Proposals for breaking changes
Test Thoroughly: Validate against all 45 rules

See .metaspec/README.md for development guide.

🔍 Use Cases

For Marketing Teams

✅ Standardize marketing operations across campaigns
✅ Ensure brand consistency with validated templates
✅ Track performance with built-in analytics

For AI Agents

✅ Structured access to marketing context via 22 Slash Commands
✅ Generate on-brand content with brand guidelines
✅ Automate campaign execution and scheduling

For Developers

✅ Integrate marketing data into apps via validated specs
✅ Build marketing automation tools on top of spec-kit
✅ Extend with custom entities and validation rules

📝 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Built with:

MetaSpec - Spec-Driven Development framework
Pydantic - Data validation
Typer - CLI framework
Rich - Terminal formatting

Generated by: MetaSpec 0.6.2
Version: 2.0.0
Release Date: 2025-11-15

For questions or issues, please open an issue.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

marketing-spec-kit

🌟 What is marketing-spec-kit?

🚀 Quick Start

Installation

Create Your First Marketing Plan

Use SDM (Spec-Driven Marketing) Commands

📋 Core Entities (9)

🔧 CLI Commands

🎯 SDM Command System (10)

Core Flow (5) - Essential Workflow

Quality Gates (3) - Recommended for Quality Assurance

Extension (2) - Feedback Loop

Workflow Patterns

🤖 Spec-Driven Marketing Architecture

Documentation

✅ Validation Rules (45)

📊 Example Specification

🏗️ Project Structure

📚 Documentation

🤝 Contributing

🔍 Use Cases

For Marketing Teams

For AI Agents

For Developers

📝 License

🙏 Acknowledgments

About

Uh oh!

Releases

Packages

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
.metaspec		.metaspec
examples		examples
memory		memory
scripts		scripts
specs		specs
src/marketing_spec_kit		src/marketing_spec_kit
templates		templates
tests/fixtures		tests/fixtures
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
marketing-spec-kit.json		marketing-spec-kit.json
pyproject.toml		pyproject.toml
uv.lock		uv.lock

License

ACNet-AI/marketing-spec-kit

Folders and files

Latest commit

History

Repository files navigation

marketing-spec-kit

🌟 What is marketing-spec-kit?

🚀 Quick Start

Installation

Create Your First Marketing Plan

Use SDM (Spec-Driven Marketing) Commands

📋 Core Entities (9)

🔧 CLI Commands

🎯 SDM Command System (10)

Core Flow (5) - Essential Workflow

Quality Gates (3) - Recommended for Quality Assurance

Extension (2) - Feedback Loop

Workflow Patterns

🤖 Spec-Driven Marketing Architecture

Documentation

✅ Validation Rules (45)

📊 Example Specification

🏗️ Project Structure

📚 Documentation

🤝 Contributing

🔍 Use Cases

For Marketing Teams

For AI Agents

For Developers

📝 License

🙏 Acknowledgments

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages