Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
310 lines (222 loc) · 14.7 KB

CONTRIBUTING.md

File metadata and controls

310 lines (222 loc) · 14.7 KB
Raw

Contributing to Digital Marketing Pro

Thank you for your interest in improving the Digital Marketing Pro plugin. This guide covers how to contribute effectively.

How to Contribute

Reporting Issues

Open a GitHub issue for:

  • Bug reports (scripts crashing, incorrect compliance rules, outdated platform specs)
  • Feature requests (new modules, additional platforms, more industry profiles)
  • Documentation improvements (unclear instructions, missing examples, outdated information)

Include:

  • Plugin version (plugin.json → version)
  • Claude Code version
  • Steps to reproduce (for bugs)
  • Expected vs. actual behavior

Submitting Changes

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/add-podcast-module)
  3. Make your changes following the conventions below
  4. Test your changes (see Testing section)
  5. Submit a pull request with a clear description of what changed and why

Plugin File Conventions

Skill Files (SKILL.md)

Every skill directory must contain a SKILL.md file with YAML frontmatter:

---
name: skill-name
description: One sentence describing when this skill should be used.
user-invocable: true
triggers:
  - natural language phrase 1
  - natural language phrase 2
  - 6-8 phrases that should trigger this skill
allowed-tools: Read Write Edit Bash Glob Grep
---

# /digital-marketing-pro:skill-name

## Purpose
What this skill does and what outcome the user gets.

## Input Required
What information the user must provide.

## Process
Numbered steps the skill follows. Step 1 must load brand context.

## Output
What the skill delivers.

## Agents Used
Which specialist agents are activated.

Skills that participate in the v3.0 engagement methodology

Skills that produce or consume engagement-state must add two extra frontmatter fields:

engagement-part: "3"          # Which part this skill produces (1-12, or "orchestrator")
view-preference: v2-primary   # v1-only / v1-primary / v2-only / v2-primary / both

view-preference controls which version of source documents the skill loads:

  • v2-primary — load v2 docs; fall back to v1 only if specific doc has no v2
  • v1-primary — load v1 docs always
  • both — load both v1 and v2 versions; the skill content compares them
  • v1-only — load only v1 (used by ideation skills + Part 5 client validation)
  • v2-only — load only v2 (used by execution-only skills)

These fields are optional for skills that do not participate in the engagement workflow. Existing v2.x skills continue to work without them.

For methodology skills, follow the conventions in section 12.11 of docs/architecture.md. The canonical examples are:

  • skills/engagement-workflow/SKILL.md
  • skills/four-core-documents/SKILL.md
  • skills/client-validation-document/SKILL.md
  • skills/growth-plan/SKILL.md
  • skills/yearly-planner/SKILL.md
  • skills/continuous-improvement-loop/SKILL.md

Module skills (16 core modules) must include a ## Brand Context (Auto-Applied) section before ## Required Context:

## Brand Context (Auto-Applied)

Before producing any marketing output from this module:

1. **Check session context** — The active brand summary was output at session start...
2. **If you need the full profile**, read: `~/.claude-marketing/brands/{slug}/profile.json`
3. **Apply brand voice** — Formality, energy, humor, authority levels...
4. **Check compliance** — Auto-apply rules for brand's target_markets...
5. **Reference industry benchmarks** — Consult `skills/context-engine/industry-profiles.md`...
6. **Use platform specs** — Reference `skills/context-engine/platform-specs.md`...
7. **Check campaign history** — Run `python campaign-tracker.py --brand {slug} --action list-campaigns`...
8. **If no brand exists**, say: "No brand profile found. Use /digital-marketing-pro:brand-setup to create one..."

Do not ask the user for information that already exists in their brand profile.

Command skills (102 slash commands) must have an explicit brand loading step as Process step 1:

1. **Load brand context**: Read `~/.claude-marketing/brands/_active-brand.json` for the active slug, then load `~/.claude-marketing/brands/{slug}/profile.json`. Apply brand voice, compliance rules for target markets (`skills/context-engine/compliance-rules.md`), and industry context. If no brand exists, ask: "Set up a brand first (/digital-marketing-pro:brand-setup)?" — or proceed with defaults.

Agent Definitions (agents/*.md)

Each agent file uses YAML frontmatter and follows this structure:

---
name: agent-name
description: One sentence describing the agent's specialty.
---

# Agent Name

## Core Capabilities
Bulleted list of what this agent can do.

## Behavior Rules
Numbered rules the agent must follow. Rule 1 should always load brand context.

## Output Format
How the agent structures its responses.

Key conventions:

  • Agents always load brand context first (Rule 1)
  • Agents reference context-engine files for compliance, benchmarks, and specs
  • Agents produce structured output (not freeform paragraphs)
  • Agents state assumptions explicitly
  • Agents include 5 additional sections: ## Tools (scripts), ## MCP Integrations, ## Memory Operations, ## Reference Knowledge, ## Collaboration (inter-agent handoffs)

Python Scripts (scripts/*.py)

Scripts must follow these conventions:

  1. Argparse CLI: Use argparse for all command-line arguments
  2. JSON output: Print structured JSON to stdout for programmatic consumption
  3. Graceful fallbacks: If optional dependencies are missing, output a fallback JSON with "fallback": true and sys.exit(0) — never crash with sys.exit(1) on missing optional deps
  4. Brand-aware: Accept --brand SLUG to load brand-specific data from ~/.claude-marketing/brands/{slug}/
  5. No hardcoded paths: Use pathlib.Path.home() / ".claude-marketing" for the data directory

Example graceful fallback:

try:
    import nltk
except ImportError:
    print(json.dumps({
        "fallback": True,
        "error": "nltk_not_installed",
        "message": "NLTK not installed. Install with: pip install nltk",
        "recommendation": "Install NLTK for automated scoring, or review manually."
    }, indent=2))
    sys.exit(0)

Reference Knowledge Files

Reference files in skill directories (e.g., kpi-frameworks.md, compliance-rules.md) should:

  • Use structured markdown with clear headings and consistent formatting
  • Include specific numbers, benchmarks, and thresholds (not vague guidance)
  • Cite the source or basis for benchmarks where possible
  • Be organized for both human reading and programmatic reference
  • Use tables for comparative data
  • Keep content current — update benchmarks annually

Execution Command Skills

Execution commands (publishing, CRM, monitoring, communication) follow additional conventions beyond the standard command SKILL.md format:

  1. Approval step required: Every execution command must include an explicit approval step before any external write operation. The process must include: "Present the execution plan to the user for review. Wait for explicit approval before proceeding."
  2. Risk level classification: Execution commands must declare their risk level (low/medium/high/critical) and the corresponding approval requirements from skills/context-engine/approval-framework.md.
  3. Rollback documentation: Commands that modify external state must describe what happens if execution fails and how to roll back.
  4. Platform verification: Commands that write to MCP platforms must verify the correct platform connection is active before executing.
  5. Execution logging: All execution commands must log results via execution-tracker.py --action log-execution.

Memory Layer Conventions

When adding or modifying memory/knowledge commands:

  1. Layer selection: Reference skills/context-engine/memory-architecture.md for which memory layer to use for each data type.
  2. Metadata requirements: All stored items must include brand slug, timestamp, data type, and source.
  3. No raw credential storage: Never store API keys, tokens, or secrets in memory layers.

Agency Credential Conventions

When working with credential profiles:

  1. Credential profiles store references, not secrets: ~/.claude-marketing/credentials/{slug}.json maps brand slugs to environment variable names, never to actual credential values.
  2. Brand isolation: Never allow operations that could leak one brand's credentials to another brand's context.
  3. Validation before execution: Always validate credential profile completeness before attempting platform operations.

Context Engine Reference Files

The 13 core reference files in skills/context-engine/ are shared across all modules:

File Purpose Update Frequency
industry-profiles.md 22 industry profiles with benchmarks Annually
compliance-rules.md 16 geographic + 10 industry regulations When laws change
platform-specs.md 20+ platform character limits, specs Quarterly
scoring-rubrics.md 7 scoring frameworks (0-100 scale) Rarely
intelligence-layer.md Adaptive learning system docs When architecture changes
guidelines-framework.md Brand guidelines structure and enforcement When guidelines system changes
execution-workflows.md 8 execution type SOPs When execution patterns change
approval-framework.md 4 risk levels + industry gates When approval rules change
platform-publishing-specs.md Platform API write specs Quarterly
memory-architecture.md 5-layer memory system docs When architecture changes
crm-integration-guide.md CRM field mapping + sync patterns When CRM integrations change
agency-operations-guide.md Multi-client management patterns When agency features change
team-roles-framework.md Role definitions + permissions When team features change

When updating these files, ensure all modules that reference them still work correctly.

Novel Feature Conventions

Predictive Scripts

Predictive scripts (forecasting, simulation, scenario modeling) must:

  1. Use stdlib only: Only random, math, and statistics from the Python standard library. No NumPy, SciPy, or pandas required.
  2. Monte Carlo defaults: Simulations should default to 10,000 iterations. Accept --iterations to override.
  3. Reproducibility: Accept --seed for deterministic runs. When a seed is provided, call random.seed(seed) before any randomization. Document the default seed behavior (None = random) in the script's --help output.
  4. Output confidence intervals: Results must include confidence intervals (e.g., p10/p50/p90) rather than single-point estimates.

Intelligence Layer

All learnings stored by the intelligence layer must include these required fields:

Field Type Description
confidence float (0-1) How confident the system is in this learning
source_agent string Which agent produced the learning
conditions object Context under which the learning applies (brand, channel, audience, etc.)
timestamp ISO 8601 When the learning was recorded
revalidation_date ISO 8601 When the learning should be re-evaluated (default: 90 days)

Learnings with confidence < 0.3 must be flagged as hypotheses, not treated as established knowledge.

Synthetic Audience

When generating synthetic audience data (panels, personas, simulated responses):

  1. Always include a confidence limitations disclaimer in the output: "These are synthetic results generated from modeled assumptions, not empirical data. Treat as hypotheses for directional guidance, not as validated research."
  2. Synthetic results are hypotheses, not data: Never present synthetic outputs as equivalent to real survey or analytics data. Label all synthetic outputs with "synthetic": true in JSON.
  3. Document assumptions: List every assumption baked into the synthetic model (sample composition, response distributions, behavioral models).

Self-Healing

Self-healing features (auto-corrections, automated fixes, adaptive adjustments) must follow these guardrails:

  1. All auto-corrections must be logged: Every automated change must be recorded via execution-tracker.py with the original value, new value, reason, and timestamp.
  2. Reversible by default: Every auto-correction must store enough state to undo it. Include a --rollback flag or equivalent mechanism.
  3. Configurable guardrails: Auto-correction limits must be configurable (e.g., max budget adjustment percentage, max bid change per cycle). Defaults should be conservative. Never exceed guardrails without explicit user approval.
  4. Escalation threshold: If a self-healing action would exceed the configured guardrail, escalate to the user instead of acting autonomously.

GEO Monitoring

Generative Engine Optimization (GEO) monitoring must use a consistent scoring rubric across all tools:

Mention Type Score Definition
Cited 10 Brand explicitly named as a source or recommendation
Mentioned 7 Brand named in a relevant context without direct endorsement
Concept-only 3 Brand's category or solution mentioned but brand not named
Absent 0 No mention of brand or relevant category
Misrepresented -5 Brand mentioned with incorrect or damaging context

All GEO scripts must use these exact values. Do not create alternative scoring scales.

Testing Your Changes

Manual Testing

  1. Skill changes: Run the modified skill command and verify output includes brand context, compliance checks, and proper formatting
  2. Script changes: Run the script directly with --brand test-brand and verify JSON output
  3. Hook changes: Validate hooks.json is valid JSON: python -c "import json; json.load(open('hooks/hooks.json'))"
  4. Reference file changes: Verify no broken markdown formatting and that modules referencing the file still produce correct output

Verification Checklist

  • hooks.json is valid JSON
  • All SKILL.md files have valid YAML frontmatter
  • Scripts exit with code 0 (even on missing optional deps)
  • Brand context loading path is explicit in all command skills
  • No hardcoded file paths (use ~/.claude-marketing/ for data, scripts/ for script calls)
  • File count hasn't changed unexpectedly (currently ~410 files including docs)

Code of Conduct

Be respectful, constructive, and professional. Marketing advice in this plugin affects real businesses — ensure all guidance is accurate, ethical, and compliant with applicable laws.

License

By contributing, you agree that your contributions will be licensed under the MIT License.