# 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:

```markdown
---
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:

```yaml
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](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`:

```markdown
## 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:

```markdown
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:

```markdown
---
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:

```python
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.
