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.4.0 introduces a distributed directory structure with 10 SDM commands for specification-driven marketing operations:

specs/      ← WHAT to achieve (Strategy specifications - Markdown)
config/     ← Configurable parameters (YAML)
templates/  ← Content templates (Markdown/Text)
data/       ← Collected metrics (JSON)
src/        ← HOW to execute (Executable code - TypeScript) ⭐

Complete workflow: Specify → Plan → Tasks → Implement → [Execute Code] → Review → Optimize

Architecture inspired by: Anthropic's Code Execution with MCP

🚀 Quick Start

Installation

# Using pip
pip install marketing-spec-kit

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

Create Your First Marketing Project

# Initialize a new project with AI-driven workflow
marketing_spec_kit init my-marketing-project
cd my-marketing-project

# The generator creates:
# ✅ memory/constitution.md       - Marketing principles
# ✅ specs/README.md               - Workflow guidance
# ✅ .marketingspeckit/commands/  - 10 SDM commands for AI
# Note: config/, templates/, data/, src/ created by /marketspec.implement

# Follow the AI-driven workflow
# Talk to AI: "Create a Q1 campaign using /marketspec.specify"
# AI generates:
#   specs/001-q1/spec.md      (Markdown specifications)
#   config/001-q1.yaml        (configuration - via /marketspec.implement)
#   templates/001-q1/         (content templates - via /marketspec.implement)
#   src/campaigns/001-q1.ts   (executable code - via /marketspec.implement)

Use SDM (Spec-Driven Marketing) Commands

New in v0.4.0: Distributed architecture with 10 commands (8 Core + 2 Extension)!

# Phase 1: Define WHAT (Specifications in specs/)
/marketspec.constitution              # → memory/constitution.md
/marketspec.specify "Q1 Growth"       # → specs/001-q1/spec.md
/marketspec.clarify                   # → specs/001-q1/clarifications.md
/marketspec.plan                      # → specs/001-q1/plan.md
/marketspec.checklist                 # → specs/001-q1/checklist.md
/marketspec.tasks                     # → specs/001-q1/tasks.md
/marketspec.analyze                   # → specs/001-q1/analysis.md

# Phase 2: Build HOW + DATA ⭐
/marketspec.implement                 # Generates:
                                      # → src/campaigns/001-q1.ts (executable code)
                                      # → src/shared/mcp-tools/*.ts (MCP wrappers)
                                      # → config/001-q1.yaml (configuration)
                                      # → templates/001-q1/ (content templates)

# Phase 3: Execute Campaign (Run Generated Code)
npm install                           # Install dependencies
ts-node src/campaigns/001-q1.ts       # Execute the campaign code
# → Code calls MCP tools (github-api, twitter-api, etc.)
# → Data collected in data/001-q1/

# Phase 4: Review & Optimize (Analysis in specs/)
/marketspec.review                    # → specs/001-q1/review.md
/marketspec.optimize                  # → specs/001-q1/optimize.md

Key Insight:

specs/ = WHAT (Strategy specifications - Markdown)
config/ = Adjustable parameters (YAML)
templates/ = Content templates (Markdown/Text)
data/ = Collected metrics (JSON)
src/ = HOW (Executable code - TypeScript) ⭐

See SDM Workflow Example for complete walkthrough!

📋 Directory Structure

marketing-spec-kit v0.4.0 uses a distributed directory structure:

`specs/` - Strategy Specifications (Markdown)

Purpose: Define WHAT to achieve

Document	Purpose	Generated By
`spec.md`	Requirements and objectives	`/marketspec.specify`
`clarifications.md`	Resolved ambiguities	`/marketspec.clarify`
`plan.md`	Marketing strategy	`/marketspec.plan`
`checklist.md`	Quality standards	`/marketspec.checklist`
`tasks.md`	Task breakdown	`/marketspec.tasks`
`analysis.md`	Consistency report	`/marketspec.analyze`
`review.md`	Performance report	`/marketspec.review`
`optimize.md`	Optimization recommendations	`/marketspec.optimize`

`config/` - Campaign Configurations (YAML)

Purpose: Configurable campaign parameters

File	Purpose	Generated By
`{seq}-{name}.yaml`	Campaign configuration	`/marketspec.implement`

`templates/` - Content Templates (Markdown/Text)

Purpose: Reusable content templates

Directory	Purpose	Generated By
`{seq}-{name}/`	Campaign-specific templates	`/marketspec.implement`

`data/` - Collected Metrics (JSON)

Purpose: Runtime collected metrics

Directory	Purpose	Generated By
`{seq}-{name}/`	Campaign data	Code execution

`src/` - Executable Code (TypeScript) ⭐

Purpose: Define HOW to execute (code calling MCP tools)

Directory	Purpose	Generated By
`campaigns/*.ts`	Campaign execution scripts	`/marketspec.implement`
`shared/mcp-tools/*.ts`	MCP tool wrappers	`/marketspec.implement`
`shared/utils.ts`	Helper functions	`/marketspec.implement`

🔧 CLI Commands

Command	Description
`init <project-dir>`	Create a new marketing project (generates `memory/`, `specs/`, `.marketingspeckit/`)
`validate <file>`	Validate YAML files in `config/` against business rules (optional)
`info`	Show toolkit version and statistics

Note: Most work is done through SDM commands (via AI), not CLI.

🎯 SDM Command System (10)

New in v0.4.0: Distributed architecture (8 Core + 2 Extension commands)

Core Commands (8) - Aligned with MetaSpec

#	Command	Purpose	Output Layer	Output File
1	`/marketspec.constitution`	Define marketing principles	`memory/`	`constitution.md`
2	`/marketspec.specify`	Define marketing requirements	`specs/`	`{seq}-{name}/spec.md`
3	`/marketspec.clarify`	Clarify objectives	`specs/`	`{seq}-{name}/clarifications.md`
4	`/marketspec.plan`	Plan marketing strategy	`specs/`	`{seq}-{name}/plan.md`
5	`/marketspec.checklist`	Generate quality standards	`specs/`	`{seq}-{name}/checklist.md`
6	`/marketspec.tasks`	Break down tasks	`specs/`	`{seq}-{name}/tasks.md`
7	`/marketspec.analyze`	Check consistency & coverage	`specs/`	`{seq}-{name}/analysis.md`
8	`/marketspec.implement`	Generate code + configs ⭐	`src/` + `config/` + `templates/`	`campaigns/{seq}-{name}.ts` + config + templates

Extension Commands (2) - Marketing-Specific

#	Command	Purpose	Output Layer	Output File
9	`/marketspec.review`	Analyze campaign results	`specs/`	`{seq}-{name}/review.md`
10	`/marketspec.optimize`	Generate optimization recommendations	`specs/`	`{seq}-{name}/optimize.md`

Distributed Directory Structure

specs/ (Markdown): Human-readable specifications and reports

WHAT to achieve (specifications, plans)
Quality standards (checklists, analysis)
Performance reports (review, optimize)

config/ (YAML): Campaign configurations

Adjustable parameters
KPIs, budgets, schedules

templates/ (Markdown/Text): Content templates

Reusable content templates
Channel-specific formats

data/ (JSON): Collected metrics

Runtime data collection
Performance tracking

src/ (TypeScript): Executable code ⭐

Campaign scripts (campaigns/*.ts)
MCP tool wrappers (shared/mcp-tools/*.ts)
Helper functions (shared/utils.ts)

Workflow Patterns

Standard Workflow (8 steps):

specify → clarify → plan → checklist → tasks → analyze → implement → [execute]

With Post-Campaign Analysis (10 steps):

specify → ... → implement → [execute campaign] → review → optimize

Quick Start (4 steps - minimal viable):

specify → plan → tasks → implement

🤖 Distributed Architecture

SDM's Role: Clear separation of concerns with distributed directories

┌───────────────────────────────────────────────────────────────┐
│  Phase 1: Define WHAT (Commands 1-7 → specs/)                │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │ /marketspec.specify   → specs/001-q1/spec.md            │ │
│  │ /marketspec.clarify   → specs/001-q1/clarifications.md  │ │
│  │ /marketspec.plan      → specs/001-q1/plan.md            │ │
│  │ /marketspec.checklist → specs/001-q1/checklist.md       │ │
│  │ /marketspec.tasks     → specs/001-q1/tasks.md           │ │
│  │ /marketspec.analyze   → specs/001-q1/analysis.md        │ │
│  └─────────────────────────────────────────────────────────┘ │
└──────────────────────────────┬────────────────────────────────┘
                               ↓
┌───────────────────────────────────────────────────────────────┐
│  Phase 2: Build HOW + DATA (Command 8) ⭐                     │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │ /marketspec.implement                                   │ │
│  │   → src/campaigns/001-q1.ts (executable code) ⭐        │ │
│  │   → src/shared/mcp-tools/*.ts (MCP wrappers)            │ │
│  │   → config/001-q1.yaml (configuration)                  │ │
│  │   → templates/001-q1/ (content templates)               │ │
│  └─────────────────────────────────────────────────────────┘ │
└──────────────────────────────┬────────────────────────────────┘
                               ↓
┌───────────────────────────────────────────────────────────────┐
│  Phase 3: Execute Campaign (Run Generated Code)               │
│   $ npm install                                               │
│   $ ts-node src/campaigns/001-q1.ts                           │
│                                                                │
│   Code execution:                                             │
│   • Loads config from config/                                 │
│   • Renders templates from templates/                         │
│   • Calls MCP tools (github-api, twitter-api, etc)            │
│   • Saves data to data/001-q1/                                │
└──────────────────────────────┬────────────────────────────────┘
                               ↓
┌───────────────────────────────────────────────────────────────┐
│  Phase 4: Review & Optimize (Commands 9-10 → specs/)          │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │ /marketspec.review   → specs/001-q1/review.md           │ │
│  │ /marketspec.optimize → specs/001-q1/optimize.md         │ │
│  └─────────────────────────────────────────────────────────┘ │
└──────────────────────────────┬────────────────────────────────┘
                               ↓
                    [Feed into next campaign]

Key Insight:

specs/ = WHAT to achieve (Strategy specifications - Markdown)
config/ = Adjustable parameters (YAML)
templates/ = Content templates (Markdown/Text)
data/ = Collected metrics (JSON)
src/ = HOW to execute (Executable code - TypeScript) ⭐

Alignment with MetaSpec: specs/ → src/
Extended for marketing: + config/ + templates/ + data/

Why Generate Code (Not Just YAML)?

Inspired by: Anthropic's Code Execution with MCP

Code execution provides major advantages:

Benefit	Description	Impact
Progressive Disclosure	Load tool definitions on-demand, not upfront	98% token savings
Context Efficiency	Filter data in execution environment, not LLM context	Faster, cheaper
Control Flow	Use code loops/conditions instead of chaining tool calls	Lower latency
Privacy	Sensitive data stays in execution environment	Better security
Testable	Standard testing frameworks (Jest, pytest)	Higher quality
Version Control	Git tracks code changes	Better collaboration

Example - Progressive Disclosure:

// Load only GitHub tools (not all 1000 tools)
import * as github from './mcp-tools/github';

// Get stars (data filtered in execution, not LLM)
const stars = await github.getStarCount({ repo: 'owner/repo' });
console.log(`Stars: ${stars}`);  // Only count logged, not full response

Documentation

✅ Validation (Optional)

marketing-spec-kit can validate YAML files in config/ directory:

# Validate campaign configurations (optional)
marketing_spec_kit validate config/001-q1-campaign.yaml

Note: Validation is optional in v0.4.0's distributed architecture:

specs/ (Markdown): No formal validation (human-reviewed)
config/ (YAML): Can be validated against business rules
src/ (TypeScript): Use TypeScript compiler and linters

Validation rules cover entities like Campaign, Channel, Tool, ContentTemplate, etc.

📊 Example Project Structure

After running /marketspec.implement, your project looks like:

my-marketing-project/
├── memory/
│   └── constitution.md                    # Marketing principles
│
├── specs/
│   └── 001-q1-campaign/
│       ├── spec.md                        # Requirements (WHAT)
│       ├── clarifications.md              # Resolved questions
│       ├── plan.md                        # Strategy architecture
│       ├── checklist.md                   # Quality standards
│       ├── tasks.md                       # Task breakdown
│       ├── analysis.md                    # Consistency report
│       ├── review.md                      # Performance report (after execution)
│       └── optimize.md                    # Optimization recommendations
│
├── config/
│   └── 001-q1-campaign.yaml               # Campaign configuration
│
├── templates/
│   └── 001-q1/
│       ├── blog-post-template.md          # Blog template
│       └── tweet-template.md              # Twitter template
│
├── data/
│   └── 001-q1/
│       ├── github-stars.json              # Collected data
│       └── traffic.json
│
└── src/
    ├── campaigns/
    │   └── 001-q1-campaign.ts             # Main execution script (HOW)
    └── shared/
        ├── mcp-tools/
        │   ├── github.ts
        │   └── twitter.ts
        ├── config-loader.ts
        └── utils.ts

Example config/001-q1-campaign.yaml:

campaign:
  id: "001-q1-campaign"
  name: "Q1 Growth Campaign"
  spec_ref: "specs/001-q1-campaign/spec.md"
  
kpis:
  github_stars:
    target: 500
    baseline: 100
    repo: "owner/repo"
    tool: "github-api"

channels:
  twitter:
    frequency: "3 posts/day"
    budget: 1000
    template: "templates/001-q1/tweet-template.md"

budget:
  total: 5000
  content: 2000
  paid_promotion: 3000

Example src/campaigns/001-q1-campaign.ts:

import * as github from '../shared/mcp-tools/github';
import { loadConfig, saveData } from '../shared/utils';

async function execute() {
  const config = await loadConfig('config/001-q1-campaign.yaml');
  const stars = await github.getStarCount({ repo: config.kpis.github_stars.repo });
  await saveData('data/001-q1/github-stars.json', { stars });
}

See examples/ for complete examples, especially examples/q1-github-stars-campaign/ for a full working project.

🏗️ Toolkit Structure

marketing-spec-kit/                      # The toolkit itself
├── README.md                           # This file
├── CHANGELOG.md                        # Version history
├── AGENTS.md                           # AI Agent guide
├── docs/
│   └── sdm-commands.md                # SDM commands documentation
│
├── templates/
│   └── sdm/
│       └── commands/                  # 10 SDM command definitions
│           ├── marketspec.constitution.md
│           ├── marketspec.specify.md
│           ├── marketspec.clarify.md
│           ├── marketspec.plan.md
│           ├── marketspec.checklist.md
│           ├── marketspec.tasks.md
│           ├── marketspec.analyze.md
│           ├── marketspec.implement.md  ⭐ (generates src/ + config/ + templates/)
│           ├── marketspec.review.md
│           └── marketspec.optimize.md
│
└── src/marketing_spec_kit/
    ├── generator.py            # Project initialization
    ├── cli.py                  # CLI (init, validate, info)
    └── validator.py            # YAML validation (optional)

📁 User Project Structure (After `init`)

my-marketing-project/                    # Created by `marketing_spec_kit init`
├── memory/
│   └── constitution.md                 # Marketing principles
│
├── specs/                              # Specifications (Markdown)
│   └── {seq}-{name}/
│       ├── spec.md                     # Requirements
│       ├── plan.md                     # Strategy
│       ├── tasks.md                    # Task breakdown
│       ├── analysis.md                 # Consistency check
│       ├── review.md                   # Performance report
│       └── optimize.md                 # Recommendations
│
├── config/                             # Configurations (YAML) - created by /marketspec.implement
│   └── {seq}-{name}.yaml               ← Campaign configuration
│
├── templates/                          # Content templates - created by /marketspec.implement
│   └── {seq}-{name}/
│       ├── tweet-template.md
│       └── blog-post-template.md
│
├── data/                               # Collected metrics (JSON) - created by code execution
│   └── {seq}-{name}/
│       ├── github-stars.json
│       └── traffic.json
│
├── src/                                # Executable code - created by /marketspec.implement
│   ├── campaigns/
│   │   └── {seq}-{name}.ts            ← Main execution script
│   └── shared/
│       └── mcp-tools/*.ts
│
└── .marketingspeckit/
    └── commands/                       # 10 SDM commands (copied from toolkit)

📚 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

✅ Define strategy in human-readable Markdown (specs/)
✅ Generate executable code and configs (src/, config/, templates/)
✅ Track performance with post-campaign analysis (review, optimize)

For AI Agents

✅ Guide campaign planning with 10 SDM commands
✅ Generate executable TypeScript code automatically
✅ Analyze performance and suggest optimizations

For Developers

✅ Validate campaign configuration YAML files (optional)
✅ Extend with custom MCP tools for data collection
✅ Build on distributed directory architecture

📝 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.9.5
Version: 0.4.0
Last Updated: 2025-11-20
Architecture: Distributed directories (specs/ + config/ + templates/ + data/ + src/)

For questions or issues, please open an issue.

Name		Name	Last commit message	Last commit date
Latest commit History 29 Commits
.metaspec		.metaspec
docs		docs
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

Folders and files

Latest commit

History

Repository files navigation

marketing-spec-kit

🌟 What is marketing-spec-kit?

🚀 Quick Start

Installation

Create Your First Marketing Project

Use SDM (Spec-Driven Marketing) Commands

📋 Directory Structure

specs/ - Strategy Specifications (Markdown)

config/ - Campaign Configurations (YAML)

templates/ - Content Templates (Markdown/Text)

data/ - Collected Metrics (JSON)

src/ - Executable Code (TypeScript) ⭐

🔧 CLI Commands

🎯 SDM Command System (10)

Core Commands (8) - Aligned with MetaSpec

Extension Commands (2) - Marketing-Specific

Distributed Directory Structure

Workflow Patterns

🤖 Distributed Architecture

Why Generate Code (Not Just YAML)?

Documentation

✅ Validation (Optional)

📊 Example Project Structure

🏗️ Toolkit Structure

📁 User Project Structure (After init)

📚 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

Uh oh!

Contributors

Uh oh!

Languages

`specs/` - Strategy Specifications (Markdown)

`config/` - Campaign Configurations (YAML)

`templates/` - Content Templates (Markdown/Text)

`data/` - Collected Metrics (JSON)

`src/` - Executable Code (TypeScript) ⭐

📁 User Project Structure (After `init`)

Packages