engagement-workflow

Files (1)

• SKILL.md

SKILL.md (first lines)

# /digital-marketing-pro:engagement-workflow — 12-Part Engagement Orchestrator

> **Script location.** If your host does not set `${CLAUDE_PLUGIN_ROOT}`, the scripts are in this plugin's `scripts/` folder, next to `skills/`. Run them with Python 3.10 or newer: `python`, or `python3` where `python` is not found (macOS, many Linux systems).

This skill orchestrates the full marketing engagement using the 12-Part sequential methodology. Every brand engagement runs through the same 12 parts in sequence, producing a canonical set of files at each stage.

## Context efficiency

Heavy skill. **Grep before Read** any referenced file, then `Read` only matched ranges with `offset` + `limit`. List the brand's workspace at `~/.claude-marketing/brands/{slug}/` (or `$CLAUDE_PLUGIN_DATA/digital-marketing-pro/brands/{slug}/` when that env var is set) before opening files. On re-invocation mid-session, skip files already in context.

Read these references before producing output:
- [engagement-flow-methodology.md](../context-engine/engagement-flow-methodology.md) — the full 12-Part flow
- [two-views-model.md](../context-engine/two-views-model.md) — v1 / v2 architecture
- [stone-vs-opinion.md](../context-engine/stone-vs-opinion.md) — confidence tagging
- [decision-matrix-rerun.md](../context-engine/decision-matrix-rerun.md) — when to re-run what
- [update-back-rule.md](../context-engine/update-back-rule.md) — versioning protocol
- [living-instruction-file-spec.md](../context-engine/living-instruction-file-spec.md) — LIF schema

## Operating Mode

This skill is invoked via the `/digital-marketing-pro:engagement` command family. The command is a thin router — **this skill is the single source of truth** for the engagement lifecycle, the checkpoint protocol, and the per-part production contract. Each subcommand maps to a specific lifecycle action. The skill calls `engagement-state.py` for persistence via:

```
python "${CLAUDE_PLUGIN_ROOT}/scripts/engagement-state.py" <subcommand> ...
```

You should never hand-edit `_engagement.json` — always go through `engagement-state.py`.

## Checkpointing & Resume (single source of truth)

Every long engagement run is resumable. The checkpoint protocol is: **init a run → save each part as it completes → finalize → publish to the visible output folder.** This lets an interrupted run (context exhaustion, user cancel, machine sleep) resume from the next un-checkpointed part instead of restarting from Part 1.

**1. On `start`, after the brand pre-condition passes, open a checkpoint run and link it to engagement state:**

```bash
python "${CLAUDE_PLUGIN_ROOT}/scripts/checkpoint-manager.py" init \
    --brand "{brand_slug}" --workflow engagement --topic "{engagement_id}"

# Record the returned run_id into _engagement.json so resume can find it:
python "${CLAUDE_PLUGIN_ROOT}/scripts/engagement-state.py" set-checkpoint-run \
    --brand "{brand_slug}" --id "{engagement_id}" --run-id "{run_id}"
```

`set-checkpoint-run` stores the run_id in `_engagement.json`, making the resume linkage real (previously the run_id was never persisted).

**2. After each part completes and passes its quality gate, the orchestrator saves that part's output:**

```bash
python "${CLAUDE_PLUGIN_ROOT}/scripts/checkpoint-manager.py" save \
    --brand "{brand}" --run-id "{run_id}" \
    --step {part_number} --content-file "{path_to_that_part_deliverable}" --extension md
```

Pass the **actual deliverable path for that part** (e.g. Part 3 saves the Four Core Documents path; Part 8 saves the Growth Plan path) — never a placeholder for a different part.

**3. Before saving Part 5 (Client Validation) and Part 8 (Growth Plan) deliverables, run the full quality gate:**

```bash
# BLOCKING gate — Part 5 and Part 8 deliverables cannot be checkpointed until this passes
/digital-marketing-pro:check "{path_to_deliverable}" --full --brand {brand}
```

If `/digital-marketing-pro:check --full` returns BLOCKED, fix the CRITICAL issues before checkpointing the part.

**4. After the final part, publish every artifact to the user-visible folder and finalize:**

```bash
python "${CLAUDE_PLUGIN_ROOT}/scripts/output-publisher.py" publish-run \
    --brand "{brand}" --run-id "{run_id}"

python "${CLAUDE_PLUGIN_ROOT}/scripts/checkpoint-manager.py" finalize \
    --brand "{brand}" --run-id "{run_id}" --status completed
```

Then point the user at the visible output folder via `/digital-marketing-pro:output-folder {brand}`.

To resume an interrupted run, use `/digital-marketing-pro:resume` — it reloads every saved part and continues from the next un-checkpointed part.

## State validation & rework caps

- **Validate a part's outputs against the manifest** before marking it complete:
  ```bash
  python "${CLAUDE_PLUGIN_ROOT}/scripts/engagement-state.py" validate-part \
      --brand "{brand}" --id "{id}" --part {N}
  ```
  This diffs the actual files on disk against the `PART_DEFINITIONS` manifest and flags missing deliverables. Use it in `file-tree` and before `next`.

- **Repair a partially-initialised engagement directory** (instead of crashing on a non-empty dir):
  ```bash
  python "${CLAUDE_PLUGIN_ROOT}/scripts/engagement-state.py" init --repair \
      --brand "{brand}" --id "{id}"
  ```
  `--repair` completes the canonical directory tree and state file on a dir that holds only partial state.

- **v2 re-run cap:** a maximum of **2 v2 re-run rounds per part** is allowed without explicit user override. The round count is stored in `_engagement.json`. If a part would exceed 2 rounds, stop and ask the user to explicitly approve further re-runs (records the override in state). This prevents unbounded re-run loops.

## Subcommands

### `/digital-marketing-pro:engagement start <brand-slug> <engagement-id>`

**Purpose:** Initialise a new engagement.

**Steps:**

1. Validate that the brand profile exists at `~/.claude-marketing/brands/{brand-slug}/profile.json`. If not, instruct the user to run `/digital-marketing-pro:brand-setup` first.
2. Run `python "${CLAUDE_PLUGIN_ROOT}/scripts/engagement-state.py" init --brand {brand-slug} --id {engagement-id}`.
3. Confirm the directory tree was created and report the next required action (Part 1 intake).
4. Walk the user through Part 1 Stone vs Opinion intake by asking the questions one batch at a time.

**Part 1 intake questions (ask in this order):**

**Stone — what the client knows for certain:**

1. Company basics: founded year, employee count, headquarters location, geographic operations
2. Business model: revenue streams, pricing tiers, primary product/service categories
3. Current marketing: channels currently active, monthly marketing spend, current measurable KPIs
4. Tech stack: CRM, email service provider, analytics setup, ad accounts
5. Customer base scale: customer count, biggest named customer, average order value if known

From indranilbanerjee/digital-marketing-pro, MIT.

More from indranilbanerjee/digital-marketing-pro