Engagement Workflow

/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/.

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 — the full 12-Part flow
• two-views-model.md — v1 / v2 architecture
• stone-vs-opinion.md — confidence tagging
• decision-matrix-rerun.md — when to re-run what
• update-back-rule.md — versioning protocol
• 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 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

For each Stone fact, capture:

• The fact itself
• Source (how the user knows / what document confirmed it)

Save each via:

python ${CLAUDE_PLUGIN_ROOT}/scripts/engagement-state.py add-stone-fact --brand {slug} --id {id} --fact-json '{"category":"...","fact":"...","source":"..."}'

Opinion — what the client believes:

1. Brand positioning: how does the client describe their position in the market?
2. Customer base: who do they think their customers are? Why do they buy?
3. Competitors: who do they consider their main competitors?
4. Growth opportunities: where do they think the biggest opportunity is?
5. What is working: what marketing activity does the client believe is working?
6. What is not working: what does the client believe is not working?

For each Opinion, capture:

• The hypothesis
• Client's evidence for it (could be intuition, anecdote, partial data)
• Research question — what would the unbiased research need to verify or refute?

Save each via:

python ${CLAUDE_PLUGIN_ROOT}/scripts/engagement-state.py add-opinion --brand {slug} --id {id} --hypothesis-json '{"category":"...","hypothesis":"...","client_evidence":"...","research_question":"..."}'

On completion of Part 1: mark Part 1 as completed via mark-part-completed --part 1, advise the user to proceed to Part 2 (External Research).

/digital-marketing-pro:engagement next [brand] [id]

Purpose: Advance to the next part.

Steps:

1. Read engagement status via engagement-state.py status
2. Identify the current part and next not-yet-completed part
3. Confirm with the user that the current part is genuinely complete (do not auto-advance — ask)
4. On confirmation, mark current as completed, advance current_part pointer
5. Brief the user on what the new part requires

/digital-marketing-pro:engagement status [brand] [id]

Purpose: Show engagement status.

Steps:

1. Run engagement-state.py status — get the full state
2. Read the Living Project Instruction File header
3. Format a human-readable summary:
   • Engagement: brand + id + start date
   • Current part: part name + days in
   • Completed parts: list
   • Pending parts: list
   • Open re-run decisions: count
   • LIF last updated: date
4. If the engagement has open items needing resolution, list them

/digital-marketing-pro:engagement file-tree [brand] [id]

Purpose: Show the engagement directory file tree.

Steps:

1. Run engagement-state.py file-tree
2. Format as an indented tree
3. Highlight files that are missing per the canonical structure. Use engagement-state.py validate-part --part {N} to diff each completed part's actual files against the PART_DEFINITIONS manifest (e.g., if Part 3 is marked completed but 3.1-business-and-sbu-analysis.md is missing, validate-part flags it deterministically instead of eyeballing).

/digital-marketing-pro:engagement validate [brand] [id]

Purpose: Run the Part 5 Client Validation flow.

Pre-condition: Parts 2, 3, 4 must be completed.

Steps:

1. Verify pre-conditions (Parts 2, 3, 4 completed)
2. Invoke the client-validation-document skill — it produces the Part 5 deliverable: a structured document presenting each finding from v1 with ACCEPT/REJECT/EDIT/DEFER options
3. Run the full quality gate on the Part 5 deliverable before it goes to the client: /digital-marketing-pro:check "{part5_path}" --full --brand {brand}. If it returns BLOCKED, fix the CRITICAL issues first (this gate is mandatory before Part 5 and Part 8 deliverables).
4. After the user reviews and provides decisions, parse them into a triggers list per the Decision Matrix categories
5. Run engagement-state.py decision-matrix --triggers "{comma-separated}" to compute the v2 re-run plan
6. Present the re-run plan to the user
7. Mark Part 5 completed; on user approval of the re-run plan, advance to Part 6

/digital-marketing-pro:engagement re-run-decision [brand] [id]

Purpose: Apply the Decision Matrix to compute v2 re-runs.

Steps:

1. Read the Part 5 Client Validation Document
2. Categorise rejected/edited findings into Decision Matrix triggers
3. Show the triggers and the computed re-runs
4. Estimate the cost (rough token count) of each re-run
5. Await user approval — they can accept, modify (skip some, add others), or reject
6. Record the executed plan via engagement-state.py record-rerun-execution

/digital-marketing-pro:engagement update-back [brand] [id] --doc <doc-id> --reason <reason>

Purpose: Apply the Update-Back Rule to bump a source document version after Part 7+.

Pre-condition: The user has already drafted the corrected document content.

Steps:

1. Read the current version of the doc
2. Confirm the correction with the user (validation step per the Update-Back Rule)
3. Bump the version via engagement-state.py bump-version --doc {id} --reason "{reason}"
4. Save the new version file with a header noting v(prev) → v(new) changes
5. Update the Living Project Instruction File via lif-log-change — it now appends the change to living-instruction-file.md and refreshes the header date, so the LIF reflects the correction immediately
6. Identify downstream documents that may need review and add to the engagement's review queue

/digital-marketing-pro:engagement lif-show [brand] [id]

Purpose: Display the Living Project Instruction File.

Steps: Run engagement-state.py lif-show and format the markdown output for readability.

/digital-marketing-pro:engagement list-engagements [brand]

Purpose: List all engagements (optionally filtered by brand).

Steps: Run engagement-state.py list-engagements --brand {slug} and format as a table.

Production shorthands

The command family also exposes four production shorthands that route straight to the part-producing skills (documented in Per-Part Production Targets below). These match the command surface one-to-one:

• /digital-marketing-pro:engagement four-core <brand> <id> [--doc 3.X] [--view v2] [--combined] — Part 3, invokes the four-core-documents skill
• /digital-marketing-pro:engagement growth-plan <brand> <id> — Part 8, invokes the growth-plan skill
• /digital-marketing-pro:engagement yearly-planner <brand> <id> — Part 8 companion, invokes the yearly-planner skill
• /digital-marketing-pro:engagement loop <brand> <id> — Part 12, invokes the continuous-improvement-loop skill