/engagement-workflow

name: engagement-workflow
description: "Run a full marketing engagement using the 12-Part methodology. Use when starting a new engagement, advancing parts, applying the Decision Matrix, or showing engagement status."
user-invocable: true
triggers:
  - start a new engagement
  - run the 12-part methodology
  - advance engagement to next part
  - show engagement status
  - apply the decision matrix
  - re-run v2 documents
  - mark engagement part complete
  - what part of the engagement are we on
allowed-tools: Read Write Edit Bash Glob Grep
engagement-part: orchestrator
view-preference: both

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

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

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

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

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

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:

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

  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 preven