Skip to content

gaidar/marketspec

BranchesTags

Repository files navigation

MarketSpec

A spec-driven CLI tool for creating consistent, on-brand marketing materials using AI assistants.

MarketSpec helps marketing teams define specifications for their content, then use those specs to generate and validate materials with AI assistants like Claude Code.

Features

  • Brand Foundation: Centralize your brand voice, messaging, audience profiles, and guidelines
  • Campaign Management: Organize marketing materials by campaign with briefs and specs
  • Spec Templates: Pre-built templates for emails, landing pages, social posts, and more
  • AI-Ready Prompts: Generate context-rich prompts for AI content generation
  • Content Validation: Validate generated content against specs and brand guidelines
  • Claude Code Integration: Slash commands for seamless AI workflow

Installation

Prerequisites

  • Node.js >= 20.19.0
  • pnpm (recommended) or npm

Install from Source

git clone https://github.com/your-org/marketspec.git
cd marketspec
pnpm install
pnpm build

Global Installation

# After building
npm link
# Now you can use 'marketspec' from anywhere

Quick Start

1. Initialize a Project

marketspec init

This creates the following structure:

marketspec/
├── brand/
│   ├── voice.md          # Brand voice characteristics
│   ├── messaging.md      # Key messaging framework
│   ├── audience.md       # Target audience profiles
│   ├── guidelines.md     # Brand guidelines
│   └── glossary.md       # Approved terms and terms to avoid
├── campaigns/            # Your marketing campaigns
├── templates/            # Spec templates
├── output/               # Generated content
├── AGENTS.md             # AI assistant instructions
└── project.md            # Project overview
.claude/
└── commands/             # Claude Code slash commands

2. Set Up Your Brand Foundation

Edit the brand documents to define your brand:

# Validate brand documents are complete
marketspec brand validate

# View brand summary
marketspec brand show

# View specific document
marketspec brand show voice

3. Create a Campaign

marketspec campaign create product-launch

This creates:

marketspec/campaigns/product-launch/
├── brief.md       # Campaign objectives and context
├── materials.md   # List of required materials
├── specs/         # Material specifications
└── assets/        # Campaign assets

4. Create Material Specs

# Create an email spec
marketspec spec create product-launch welcome-email --template email

# Create a landing page spec
marketspec spec create product-launch main-landing --template landing-page

# List specs in campaign
marketspec spec list product-launch

5. Generate Content

# Generate a prompt for AI content creation
marketspec generate product-launch welcome-email

# Generate prompts for all materials
marketspec generate product-launch --all

# Generate with A/B variations
marketspec generate product-launch welcome-email --variations 3

6. Validate Content

# Validate a single material
marketspec validate product-launch welcome-email

# Validate all materials in campaign
marketspec validate product-launch --all

# Generate validation report
marketspec validate product-launch --report

Commands Reference

Initialization

marketspec init              # Initialize new project
marketspec init --force      # Overwrite existing files

Brand Management

marketspec brand validate              # Validate brand documents
marketspec brand show                  # Show brand summary
marketspec brand show <document>       # Show specific document (voice, messaging, audience, guidelines, glossary)
marketspec brand check <file>          # Check content against brand guidelines

Campaign Management

marketspec campaign create <name>           # Create new campaign
marketspec campaign list                    # List all campaigns
marketspec campaign show <name>             # Show campaign details
marketspec campaign clone <source> <target> # Clone campaign as template
marketspec campaign archive <name>          # Archive completed campaign
marketspec campaign archive <name> --yes    # Archive without confirmation

Spec Management

marketspec spec create <campaign> <name> --template <type>  # Create spec from template
marketspec spec list <campaign>                              # List specs in campaign
marketspec spec show <campaign> <name>                       # Show spec details
marketspec spec validate <campaign> <name>                   # Validate single spec
marketspec spec validate <campaign> --all                    # Validate all specs

Available Templates:

  • email - Marketing emails
  • landing-page - Landing pages
  • social-post - Social media posts
  • blog-post - Blog articles
  • ad-copy - Advertising copy
  • video-script - Video scripts
  • case-study - Case studies
  • one-pager - One-page documents
  • press-release - Press releases

Content Generation

marketspec generate <campaign> <material>              # Generate prompt
marketspec generate <campaign> --all                   # Generate all prompts
marketspec generate <campaign> <material> --variations 3    # Generate with variations
marketspec generate <campaign> <material> --feedback "text" # Regenerate with feedback

Content Validation

marketspec validate <campaign> <material>              # Validate single material
marketspec validate <campaign> --all                   # Validate all materials
marketspec validate <campaign> --report                # Generate validation report

Dashboard & Export

marketspec view                        # Show project dashboard
marketspec view <campaign>             # Show campaign details

marketspec export <campaign>           # Export to JSON
marketspec export <campaign> --format md      # Export to Markdown
marketspec export <campaign> --output path    # Custom output path

Configuration

marketspec config              # Show effective configuration
marketspec config --json       # Show configuration as JSON

Utilities

marketspec update              # Regenerate AGENTS.md and slash commands
marketspec update --commands   # Update only slash commands

marketspec completion bash     # Generate bash completions
marketspec completion zsh      # Generate zsh completions
marketspec completion fish     # Generate fish completions
marketspec completion --install  # Show installation instructions

Configuration

MarketSpec uses a layered configuration system:

  1. Default values (built-in)
  2. User config (~/.marketspec/config.yaml)
  3. Project config (./marketspec.config.yaml)
  4. Environment variables (highest priority)

Configuration File

# marketspec.config.yaml
version: 1

brand:
  path: ./marketspec/brand
  required:
    - voice.md
    - messaging.md
    - audience.md

campaigns:
  path: ./marketspec/campaigns
  archive_path: ./marketspec/campaigns/archive

output:
  path: ./marketspec/output
  format: markdown  # or 'json'

validation:
  strict: true
  fail_on_warnings: false

ai:
  default: claude
  context_limit: 100000
  include_examples: true

templates:
  path: ./marketspec/templates
  custom: true

Environment Variables

Override any configuration with environment variables:

# Override validation strictness
export MARKETSPEC_VALIDATION_STRICT=false

# Override output format
export MARKETSPEC_OUTPUT_FORMAT=json

# Override AI context limit
export MARKETSPEC_AI_CONTEXT_LIMIT=50000

Claude Code Integration

MarketSpec installs slash commands for use with Claude Code:

Command Description
/ms-generate <campaign> [material] Generate content from spec
/ms-validate <campaign> [material] Validate content against spec
/ms-brand-check Check content against brand guidelines
/ms-variations <n> Generate content variations
/ms-brief <campaign> Display campaign brief
/ms-spec <campaign> <material> Display material spec
/ms-voice Display brand voice guidelines
/ms-status <campaign> Display campaign progress

Example Workflow with Claude Code

  1. Open your project in Claude Code
  2. Use /ms-brief product-launch to review the campaign
  3. Use /ms-spec product-launch welcome-email to see requirements
  4. Ask Claude to generate content based on the spec
  5. Use /ms-validate product-launch welcome-email to check the result

Workflow Examples

Complete Campaign Workflow

# 1. Initialize project (first time only)
marketspec init

# 2. Set up brand foundation
# Edit marketspec/brand/*.md files
marketspec brand validate

# 3. Create campaign
marketspec campaign create spring-sale

# 4. Define campaign brief
# Edit marketspec/campaigns/spring-sale/brief.md

# 5. Create material specs
marketspec spec create spring-sale promo-email --template email
marketspec spec create spring-sale sale-page --template landing-page
marketspec spec create spring-sale social-announcement --template social-post

# 6. Fill in spec requirements
# Edit each spec file in marketspec/campaigns/spring-sale/specs/

# 7. Validate specs
marketspec spec validate spring-sale --all

# 8. Generate AI prompts
marketspec generate spring-sale --all

# 9. Create content using AI (Claude Code or copy prompts)

# 10. Validate content
marketspec validate spring-sale --all --report

# 11. View progress
marketspec view spring-sale

# 12. Export when complete
marketspec export spring-sale

# 13. Archive campaign
marketspec campaign archive spring-sale

Brand Check Workflow

# Check any content file against brand guidelines
marketspec brand check path/to/content.md

# This checks for:
# - Prohibited terms from glossary
# - Brand voice compliance
# - Terminology consistency

A/B Testing Workflow

# Generate multiple variations
marketspec generate spring-sale promo-email --variations 3

# AI will produce labeled variations:
# - Variation 1: [approach A]
# - Variation 2: [approach B]
# - Variation 3: [approach C]

Validation Rules

Brand Validation (BRAND-*)

  • BRAND-001: Content MUST NOT use terms from "avoid" list in glossary

Campaign Validation (CAMP-*)

  • CAMP-001: Campaign MUST have brief.md
  • CAMP-002: Campaign MUST have materials.md
  • CAMP-003: Each material in checklist MUST have a spec
  • CAMP-004: Campaign brief MUST have Objective section
  • CAMP-005: Campaign brief SHOULD have Success Metrics

Spec Validation (SPEC-*)

  • SPEC-001: Spec MUST have an Objective section
  • SPEC-002: Spec MUST have at least one Key Message
  • SPEC-003: Spec MUST have at least one Requirement with SHALL/MUST
  • SPEC-004: Spec MUST have at least one Acceptance Criteria scenario
  • SPEC-005: Spec SHOULD have Target Audience defined
  • SPEC-006: Spec SHOULD reference brand foundation documents
  • SPEC-007: Requirements MUST have unique IDs (REQ-XXX)
  • SPEC-008: CTA requirements MUST specify destination

Content Validation (CONT-*)

  • CONT-001: Content MUST satisfy all SHALL/MUST requirements
  • CONT-002: Content MUST include all Key Messages marked MUST
  • CONT-003: Content MUST pass all Acceptance Criteria scenarios
  • CONT-004: Content SHOULD satisfy all SHOULD requirements
  • CONT-005: Content MUST NOT contain prohibited terms from glossary
  • CONT-006: Content MUST match specified format requirements
  • CONT-007: Content SHOULD match brand voice characteristics
  • CONT-008: CTAs MUST match specified CTA requirements

Project Structure

your-project/
├── marketspec/
│   ├── brand/
│   │   ├── voice.md          # Brand voice characteristics
│   │   ├── messaging.md      # Core messaging and value props
│   │   ├── audience.md       # Target audience profiles
│   │   ├── guidelines.md     # Visual and content guidelines
│   │   └── glossary.md       # Approved terms and terms to avoid
│   │
│   ├── campaigns/
│   │   ├── [campaign-name]/
│   │   │   ├── brief.md      # Campaign objectives
│   │   │   ├── materials.md  # Required materials checklist
│   │   │   ├── specs/        # Material specifications
│   │   │   │   ├── email.md
│   │   │   │   └── landing-page.md
│   │   │   └── assets/       # Campaign-specific assets
│   │   │
│   │   └── archive/          # Archived campaigns
│   │
│   ├── output/
│   │   └── [campaign-name]/
│   │       └── [material]/
│   │           ├── prompt.md     # Generated AI prompt
│   │           ├── content.md    # Generated content
│   │           └── validation.md # Validation results
│   │
│   ├── templates/            # Custom spec templates
│   ├── AGENTS.md             # AI assistant instructions
│   └── project.md            # Project overview
│
├── .claude/
│   └── commands/             # Claude Code slash commands
│
└── marketspec.config.yaml    # Project configuration

Shell Completions

Install shell completions for better CLI experience:

Bash

marketspec completion bash > ~/.marketspec-completion.bash
echo 'source ~/.marketspec-completion.bash' >> ~/.bashrc
source ~/.bashrc

Zsh

marketspec completion zsh > ~/.marketspec-completion.zsh
echo 'source ~/.marketspec-completion.zsh' >> ~/.zshrc
source ~/.zshrc

Fish

marketspec completion fish > ~/.config/fish/completions/marketspec.fish

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test

# Watch mode for tests
pnpm test:watch

# Type checking
pnpm lint

Technical Stack

Component Technology
Runtime Node.js >= 20.19.0
Language TypeScript 5.x
CLI Framework Commander.js
Prompts @inquirer/prompts
Styling Chalk
Spinners Ora
Schema Validation Zod
Markdown marked, gray-matter
Testing Vitest
Package Manager pnpm

License

MIT

About

Marketing framework for AI content production

Resources

Readme
Activity

Stars

9 stars

Watchers

1 watching

Forks

2 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages