ContentForge — Enterprise Content Production

Transform a content requirement into a publication-ready, fact-checked, brand-compliant, SEO-optimized piece through a 10-phase autonomous agent pipeline (plus Step 0.5 title curation) with three-layer fact verification and 10 quality gates.

Context efficiency

Pipeline phase. Grep before Read for references/, humanization-patterns.json, brand voice profiles. Hand subagents artifact file paths plus a ≤10-line summary — never reload or inline full drafts (see Context & Handoff Rules). On /contentforge:resume, load run.json plus only the artifacts the next phase contractually needs.

Execution Protocol (CRITICAL — read first)

This skill orchestrates 10 phases plus Step 0.5 (Title Curation). Each numbered phase MUST be executed by invoking its dedicated subagent via the `Task` tool — DO NOT generate the deliverable yourself in a single inference pass. A single-pass generation skips the quality gates, fact-checking layers, humanizer 43-pattern catalog (29 core + 6 structure/framing + 8 detector-signal), and reviewer scoring that define ContentForge.

The one exception is Step 0.5: title curation is performed inline by the orchestrator (no subagent), because it requires user interaction and subagents must never wait on the user. Any subagent that needs a user decision returns a {"status": "needs_user_decision", ...} payload to the orchestrator, which owns all user interaction (including image-generation opt-in/approval).

Portable execution lane — platforms without subagent dispatch (Codex, ChatGPT, single-context clients)

If your platform has no subagent/Task dispatch, the pipeline still runs — sequentially, in this conversation, with nothing waived:

1. Each phase's contract is its agent file. Before executing a phase, Read agents/{NN}-{name}.md from the plugin directory and follow it as your instructions for that phase — INPUTS, EXECUTION STEPS, OUTPUT FORMAT, and the gate. The files are plain markdown written to be executable by whoever holds them; a subagent was always just a fresh context around the same text.
2. Same artifacts, same names, same gates. Write every phase artifact to the run directory exactly as the Pipeline Contract specifies, checkpoint after each phase, and run every gate script. The auditability of a run must not depend on which platform produced it.
3. What changes: ignore per-agent maxTurns (they bound subagent sessions, not you); "return as your final output" means "write the artifact, then continue"; Progress Updates print inline. What does not change: the phase order, the loop budgets, the gate criteria, and the rule that a needs-user-decision moment stops for the user.
4. Context discipline replaces context isolation. Subagents exist to give each phase a clean context. Without them, do not carry a phase's working notes forward — after checkpointing a phase, work only from the artifacts on disk, exactly as a fresh subagent would.
5. Environment names: on Agent Plugins 1.0 hosts the plugin root is ${PLUGIN_ROOT} and persistent data is ${PLUGIN_DATA}; where a command below says ${CLAUDE_PLUGIN_ROOT}, use whichever of the two names your host defines. The scripts themselves accept both data-dir spellings. 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).

Step 0 — Initialize the run (orchestrator only, before Step 0.5)

# 1. Create the checkpoint run (returns run_id). Capture run metadata so a
#    cross-session resume can recover keyword, audience, word count, and tone.
RUN_RESULT=$(python "${CLAUDE_PLUGIN_ROOT}/scripts/checkpoint-manager.py" init \
    --brand <brand-slug> --topic "<topic>" --content-type <type> \
    --keyword "<primary keyword>" --audience "<audience>" \
    --word-count <n> --tone "<tone>")
# These flags land in run.json under meta.keyword / meta.audience /
# meta.word_count / meta.tone — use those exact key names when reading them back.
# Parse RUN_ID from the JSON result's "run_id" field.

# 2. Initialize the performance tracker for this run.
python "${CLAUDE_PLUGIN_ROOT}/scripts/pipeline-tracker.py" --action init \
    --brand <brand-slug> --run-id "$RUN_ID" --content-type <type> --topic "<topic>"

Rules:

• pipeline-tracker.py is called by the orchestrator only — subagents never call it.
• Step 0.5 is exempt from tracker calls (no phase-start/phase-end for 0.5). After the title is confirmed, checkpoint it directly (see contract table).
• If the user supplied their own draft (--source-draft <path>, or they paste/dictate their own rough words), copy it verbatim to {run_dir}/source-draft.md here in Step 0 and set "source_draft": true in run.json. Do not clean it up on the way in — the mess is the signal. See "Bring your own words" below.

Required Per-Phase Workflow (Phases 1–8)

For every numbered phase:

1. Mark phase start (orchestrator):

   python "${CLAUDE_PLUGIN_ROOT}/scripts/pipeline-tracker.py" --action phase-start --brand <slug> --run-id "$RUN_ID" --phase <N>

1. Call `Task` with the phase's qualified `subagent_type` (e.g. contentforge:researcher). The Task prompt contains ONLY:

• the artifact file paths the phase reads (per the Pipeline Contract table),
• a ≤10-line orchestrator summary of pipeline state,
• the brand-profile path (required for phases 0.5, 3, 5, 6, 6.5, 7),
• the original-requirements block (topic, confirmed title, content type, audience, primary keyword, word-count target, tone).

Subagents Read what they need from those paths. Never inline a full draft into a Task prompt.

1. Verify the quality gate yourself. Gate ownership belongs to the orchestrator: check the returned artifact against the gate criteria in the Pipeline Contract table — count sources, check word count and citation density, and run python "${CLAUDE_PLUGIN_ROOT}/scripts/text-metrics.py" --file <artifact-path> [--keyword "<primary keyword>"] for burstiness, Flesch-Kincaid grade, and keyword-placement checks (--file is required). A subagent's self-reported "PASS" alone is not a gate pass.

If a subagent returns nothing, or stops mid-sentence: audit the disk before you re-run it. A live run had its output-manager complete the .docx, all four delivery copies and the tracking update, then return only "Now generating the .docx with the real script." — no report, and its contracted phase-8-output.json unwritten. Re-running it blind would have regenerated finished work; declaring the phase failed would have been false. The principle above already implies the remedy — disk state is the authority, not the message — so make it the procedure: list the run directory, check which contracted artifacts exist, verify those against the gate, and ask the SAME agent for the missing piece rather than starting a new one. Only treat a phase as un-run when its artifacts are genuinely absent.

The same rule applies on resume: checkpoint-manager.py status reports orphaned_artifacts for phases whose artifact exists but was never checkpointed. Never re-run a phase listed there without looking at what is already on disk — but never checkpoint it unverified either. An unverified artifact is a claim, not a pass.

1. On gate PASS, checkpoint the artifact so the run is resumable:

   python "${CLAUDE_PLUGIN_ROOT}/scripts/checkpoint-manager.py" save \
       --brand <slug> --run-id "$RUN_ID" --phase <N> --content-file <artifact-path> --extension <md|json|txt>

Phases 3.5 and 6 also produce a companion manifest (phase-3.5-visual-manifest.json, phase-6-structure-manifest.json) — place it at its canonical path inside the same run directory.

1. Mark phase end with the output word count:

   python "${CLAUDE_PLUGIN_ROOT}/scripts/pipeline-tracker.py" --action phase-end --brand <slug> --run-id "$RUN_ID" --phase <N> --content-words <count>

1. Emit the audit line (so users can see real-time progress):

   [PHASE-AUDIT] phase=<N> name=<name> status=<PASS|FAIL> output_summary="<one line>" gate=<PASS|FAIL>

1. On gate FAIL, loop per the contract table's loop-target column. Before looping, record the loop and check limits:

   python "${CLAUDE_PLUGIN_ROOT}/scripts/checkpoint-manager.py" loop --brand <slug> --run-id "$RUN_ID" --edge phase_<N>_to_<target>

Limits: max 2 loops per edge, max 5 loops total per run. If a limit is reached: do NOT loop — mark the run for human review, finalize --status failed, and halt. When Phase 7 orders rework, the pending_rework field in run.json records the target phase and the reviewer's feedback so /contentforge:resume continues the rework instead of skipping it. Do not overwrite the saved checkpoint of an upstream phase that already passed — re-save only the looped phase when it passes.

Lifecycle steps (orchestrator-owned, v4.0)

Two small steps wire each run into the brand's living state. Both are cheap, both are honest about missing inputs, and neither ever blocks a run:

1. After Gate 1 passes — merge the run's verified link inventory into the

brand profile, so the reconnaissance stops evaporating with the run:

   python "${CLAUDE_PLUGIN_ROOT}/scripts/harvest-brand-pages.py" \
       --merge-inventory <run_dir>/phase-1-link-inventory.json --brand <slug>

Service/product and authority rows upsert (existing manual curation is never overwritten — stamps refresh only); conversion rows only STAGE under brand_pages.recon_candidates for the user to confirm, because a CTA is a commercial decision. If the inventory file is missing (pre-4.0 agent, no website), report that and continue — never fabricate rows.

1. Before dispatching Phase 3 — ask telemetry for drafter advisories:

   python "${CLAUDE_PLUGIN_ROOT}/scripts/telemetry.py" advisories --brand <slug>

When status is ok and advisories exist, append their brief_lines to the Phase 3 Task prompt's requirements block. When insufficient_history, append nothing — the floor is the point; a brief fed from fewer runs than the floor is fed from anecdote. Advisories inform drafting style only: they NEVER modify a gate, a threshold, or a verdict.

Image approval (orchestrator-owned, after Phase 3.5)

The visual-asset-annotator never waits on the user. It generates candidates (when image generation is opted in) and records each in phase-3.5-visual-manifest.json with approved_by_user: false. After Gate 3.5 passes, the orchestrator presents the generated visuals to the user for approval:

1. Show each generated asset (path + description + placement) and ask approve / regenerate / drop.
2. Update approved_by_user in the manifest for approved assets.
3. For rejects, re-invoke contentforge:visual-asset-annotator with the rejection feedback (counts as a Phase 3.5 re-run, not a loop edge).
4. Phase 8 embeds only assets with approved_by_user: true — unapproved assets stay out of the .docx.

If the annotator returns {"status": "needs_user_decision", ...} (e.g., image-generation opt-in was never given), ask the user, then re-invoke with the answer.

Pipeline Contract (inputs → outputs → gate → loop target)

All artifacts live in the canonical run directory ~/.claude-marketing/{brand-slug}/runs/{run_id}/ alongside run.json (the manifest).

The machine-readable form of this table is `config/pipeline-graph.json`, and that file is authoritative for the pipeline's shape — nodes, reads/writes, gates, budgeted loop edges. This table narrates it for humans; tests/test_pipeline_contract_graph.py fails the build if the two (or the agent files, or checkpoint-manager.py, or run-audit.py) ever disagree. Before v4.0 this contract lived as prose in four places at once, and they drifted twice in ways no unit test could see.

That is 10 quality gates — one for each of phases 1, 2, 3, 3.5, 4, 5, 6, 6.5, 7, and 8.

Single source of truth for numbers: approval thresholds, loop bands, dimension weights, dimension minimums, and industry overrides live in config/scoring-thresholds.json. Prose in this document references those values; if they ever disagree, the config wins.

Context & Handoff Rules

• Subagents receive artifact paths, a ≤10-line orchestrator summary, the brand-profile path (phases 0.5, 3, 5, 6, 6.5, 7), and the original-requirements block. They Read what they need.
• Never inline a full draft into a Task prompt, and never reload a full draft into the orchestrator's context when a path reference will do.
• The reviewer (Phase 7) must receive the paths of all prior artifacts, not just the Phase 6.5 output.

Final Output Requirements

After Phase 8 completes, the output-manager subagent must produce a Microsoft Word `.docx` file by calling:

python "${CLAUDE_PLUGIN_ROOT}/scripts/generate-docx.py" \
    --content <article.md> \
    --output <local-path>.docx \
    --reports <reports.json> \
    --brand "<brand>" \
    --content-type <type>

The .docx must contain: title page, full article body, sources/citations, Appendix A (SEO Scorecard), Appendix B (Quality Scorecard), Appendix C (Production Details).

Dual-copy save: the .docx is written into the run directory (~/.claude-marketing/{brand-slug}/runs/{run_id}/) AND copied to the user-visible folder ~/Documents/ContentForge/{Brand}/. Always tell the user the ~/Documents/ContentForge/ path. If the brand has Google Drive configured (tracking.backend == "google_sheets" with a tracking.google_drive.folder_id), additionally upload the .docx via drive-uploader.py.

Then audit, and only then finalize:

# 1. Re-derive every gate from the artifacts. This is not optional ceremony:
#    finalize --status completed REFUSES without a fresh CLEAN verdict on disk.
python "${CLAUDE_PLUGIN_ROOT}/scripts/run-audit.py" --brand <slug> --run-id "$RUN_ID"

# 2. Close the run.
python "${CLAUDE_PLUGIN_ROOT}/scripts/checkpoint-manager.py" finalize --brand <slug> --run-id "$RUN_ID" --status completed

What the audit is. run-audit.py re-checks the finished run the way an outside auditor would: every completed phase has its artifact, no orphaned artifacts in a finalized run, the delivered body carries no production scaffolding and anchors every generated asset, the authorship record matches a fresh measurement, no fix-ledger correction was lost or undone, an APPROVED decision is backed by its own score, and no completed status hides a blocked publication. Every one of those is a failure that actually happened in a real run while every individual artifact looked healthy. It also resolves the approve line, weights and dimension minimums from config for the review's industry (and the brand profile's, whichever is stricter) and fails a review that disagrees with them, recomputes the composite from the review's own dimension scores, and holds the recorded loop counts to the config's caps (the smaller cap governs). The verdict lands in run-audit.json inside the run directory, together with a content fingerprint of the files it read: finalize --status completed refuses if any of them changed after the audit.

When the audit fails: fix the findings and re-run it — or, if the run is legitimately unpublishable as it stands (an open requires_human blocker, say), finalize with --status blocked, which needs no audit because it claims nothing. finalize --skip-audit exists as an escape hatch that stamps audit_skipped: true into run.json: the absence of verification becomes part of the record rather than a silence.

Scorecard page (after `finalize`, completed or blocked). Always build the one-page local scorecard — it is the fallback and the source of truth. Skip it only if the script exits 2 (no review to show):

python "${CLAUDE_PLUGIN_ROOT}/scripts/scorecard-html.py" --run-dir ~/.claude-marketing/<slug>/runs/"$RUN_ID"

It reads only the run's own files, says so on the page when the audit is missing or stale, and never invalidates the audit. Give the user the local path from its JSON result. Then, only if this session has a tool that publishes an HTML page, offer to publish it as a private page and publish only on the user's explicit yes; never say it is shared. With no such tool, say so in one line and give the local path.

Why This Matters

Skipping the Task-tool orchestration means: no real fact-checking, no real humanizer (43-pattern AI removal won't fire, including detector-signal patterns 36-43), no real reviewer scoring — the pipeline becomes single-pass content generation labeled with fake phase names. The audit trail (run.json, the per-phase checkpoint artifacts, [PHASE-AUDIT] lines, real reviewer score) is the proof of execution. If those artifacts don't exist after a run, the pipeline didn't actually run.

When to Use

Use /contentforge when you need:

• Single high-quality content piece (article, blog, whitepaper, FAQ, research paper)
• Research-backed content with verified citations
• Brand-compliant content for regulated industries (Pharma, BFSI, Healthcare, Legal)
• SEO-optimized content with keyword targeting and meta tags
• Natural-sounding content with AI patterns removed (Phase 6.5 Humanizer)

For multiple pieces, use /contentforge:batch-process — a prioritized, checkpointed queue that runs the same pipeline per piece.

Express Lane (bring your own research)

When the user already has the research — pasted sources, internal notes with URLs, an existing source dossier — and asks for speed ("express", "I have my own sources", "quick article from my notes", or --express), run the EXPRESS phase set instead of the full pipeline. Verification is the product; ceremony is optional. Express is fast because the intake replaces Phase 1's deep research hunt — which dominates full-pipeline wall-clock — not because it skips craft. It keeps every verification gate AND the craft passes that make the piece read human, and drops only the phases whose value depends on surfaces outside the prose:

Skipped by default, each re-addable by flag: Phase 3.5 visuals (--with-visuals) and Phase 6 SEO/GEO (--with-seo) — the two phases whose value depends on production surfaces outside the prose (asset creation, search targeting). When a flag re-adds a phase, its full gate comes with it — there is no gate-less phase in any lane. The craft passes may be dropped only by explicit request (--skip-structure / --skip-humanizer); a chosen skip is recorded in skipped_phases like any other, and the reviewer then scores those qualities from the piece itself.

Record the lane: write "mode": "express" and the skipped_phases list into run.json at run start — the reviewer and output-manager read it to apply the express contracts. A run without mode is a full run.

What express is NOT: it is not a lower quality bar — Gates 2, 4, and 7 are identical, and the piece is still proofread (Gate 5) and humanized (Gate 6.5) unless the user explicitly opted out. It produces a verified, validated, proofread, humanized, reviewed piece WITHOUT keyword optimization or visuals. Say this plainly to the user when they choose express, and offer --with-seo / --with-visuals if they hesitate.

Bring your own words (--source-draft)

The pipeline's default mode writes from research. This mode keeps the author in the piece.

Give it your own rough draft — a voice-note transcript, a wall of bullets, three angry paragraphs typed at midnight — and ContentForge builds the article around your sentences instead of over them. Quality of the input is irrelevant; authorship is the whole point.

/contentforge:contentforge "why our review estimates were wrong" --source-draft ./notes.md

What changes:

Three honest limits, stated plainly:

• Your sentences are your voice, not verified facts. Anything factual the pipeline adds still comes from the Phase 2 ledger. If one of your claims contradicts the research, it gets flagged for you, not silently corrected — you decide.
• The authored disclosure has to be earned. It appears only when at least 25% of the finished words are yours verbatim AND none of your sentences were rewritten or dropped. It can never be turned on by asking; it is read off the record. A disclosure that overstates human authorship is the one kind a reader cannot check, so this direction is one-way by design.
• There is no target ratio and nothing here is aimed at a detector. author_word_share exists so the disclosure can be accurate. Writing more of the piece yourself makes it more yours; it is not a score, and no number turns text "human enough".

What This Command Does

Runs your content through 10 specialized agents, each behind a quality gate:

1. Research Agent — SERP analysis, source mining, competitive analysis, structured outline
2. Fact Checker — URL verification, claim validation, confidence scoring
3. Content Drafter — First draft with brand voice, SME calibration via industry knowledge packs
4. Visual Asset Annotator — Chart generation from verified stats, visual markers, asset manifest
5. Scientific Validator — Hallucination detection, domain-specific validation, logic validation
6. Structurer & Proofreader — Grammar/spelling correction, readability optimization, brand compliance
7. SEO/GEO Optimizer — Keyword placements, meta tag generation, internal linking markers
8. Humanizer — AI pattern removal (43-pattern catalog), content-derived sentence variation (burstiness advisory), brand personality
9. Reviewer — 5-dimension quality scoring (weights per config/scoring-thresholds.json)
10. Output Manager — .docx with embedded charts and internal links, dual-copy save, optional Drive upload

Quality Gates: 10 gates (phases 1–8 including 3.5 and 6.5). On failure the pipeline loops per the contract table — max 2 loops per edge, max 5 total, then human escalation.

Required Inputs

Minimum Required:

• Topic — What the content is about (e.g., "AI in Healthcare", "remote work productivity")
• Content Type — article, blog, whitepaper, faq, research_paper, video_script, case_study, newsletter
• Brand — Which brand profile to use (create with /contentforge:cf-style-guide if new brand). See No-Brand Mode below if none exists.

Pre-Flight Validation: After gathering inputs, validate the brand profile for completeness (voice, guardrails, audience, industry pack). For regulated industries (pharma, BFSI, healthcare, legal), guardrails are required — warn if they're empty and ask whether to proceed or update the profile first.

Optional:

• Target Audience — Who this content is for (e.g., "Healthcare CIOs")
• Word Count — Target length (defaults to content type standard)
• Primary Keyword — Main SEO keyword to optimize for
• Tone — Overrides brand default (authoritative, conversational, technical, witty)
• `--sources=<urls or file>` — User-supplied reference URLs (required in No-Web Mode; otherwise merged into Phase 1 research)
• `--title="Exact Title"` — Non-interactive title bypass (see Title Curation)

No-Brand Mode

If the user has no brand profile and declines to create one:

• Proceed with generic defaults (neutral professional voice, no terminology enforcement).
• Phase 5 skips the brand-compliance sub-check.
• Phase 7 scores the Brand Compliance dimension as `SKIPPED` and flags the run for manual review; the Quality Scorecard notes "no brand profile configured."
• Regulated-industry topics (pharma, BFSI, healthcare, legal) must NOT run in no-brand mode — require a profile with guardrails first.

No-Web Mode

If web research is unavailable (offline, no search tool, MCP down):

• Require user-supplied sources via --sources=.
• Skip SERP analysis; build the outline from the provided sources.
• Mark every citation "user-provided, unverified" in the fact-check ledger.
• Phase 7 caps Citation Integrity at 6.0 and notes the cap in the scorecard.
• If neither web access nor user sources are available, stop and tell the user research is impossible — do not fabricate sources.

How to Use

Interactive Mode (Recommended for First-Time Users)

/contentforge

Prompts you for:

1. Topic (the subject — NOT the final title)
2. Content Type (select from 5 options)
3. Brand (select from existing profiles)
4. Target Audience
5. Word Count (or use default)
6. Primary Keyword

Then generates 4-5 title options (different angles: benefit-driven, how-to, data-driven, question-based, contrarian). You select, modify, or provide your own title. Pipeline starts only after title confirmation.

Quick Mode (Topic Provided)

/contentforge "AI in Healthcare" --type=article --brand=acmemed --audience="Healthcare CIOs" --keyword="AI healthcare trends"

Even in quick mode, the system generates title options and asks you to select before starting Phase 1 — unless you pass --title.

Non-Interactive Mode (evals, batch, CI)

/contentforge "AI in Healthcare" --type=article --brand=acmemed --title="How AI Is Reshaping Hospital Diagnostics"

--title skips option generation and uses the given title verbatim. The bypassed title is still checkpointed as phase-0.5-title.txt.

Use Existing Google Sheet Requirement

/contentforge --sheet-url=https://docs.google.com/spreadsheets/d/ABC123 --row=5

Reads requirement from Row 5 of the sheet.

What Happens

Step 0.5: Title Curation — MANDATORY, inline

Before the pipeline starts, the orchestrator (inline — no subagent, no tracker calls) generates 4-5 SEO-optimized title options using the topic, content type, brand voice, audience, and primary keyword. Each title takes a different angle:

• Benefit-driven — leads with reader value
• How-to / Tactical — actionable, instructional
• Data-driven / Stat-led — opens with a number or trend
• Question-based / Curiosity — provokes the reader
• Contrarian / Unexpected — challenges convention

You select, modify, or provide your own title. The confirmed title becomes the anchor for the entire pipeline — research, outline, SEO, and final output all flow from it.

Do NOT auto-select a title. The only exception is an explicit --title="..." bypass, which uses the supplied title verbatim (for non-interactive runs and evals). Either way, checkpoint the confirmed title as phase-0.5-title.txt before Phase 1.

Phases 1–8 at a glance

Gate criteria and loop targets for every phase are defined once, in the Pipeline Contract table above.

• Phase 1: Research — SERP analysis anchored on the confirmed title; mines 12–15 authoritative sources; competitor analysis; structured outline. Gate 1.
• Phase 2: Fact Checking — verifies all URLs are live, validates claims against sources, assigns confidence tiers, flags unverifiable claims for removal or re-sourcing. Gate 2.
• Phase 3: Content Drafting — first draft in brand voice with inline citations (APA format), targeting word count ±10%. Gate 3.
• Phase 3.5: Visual Assets — charts from verified stats, visual markers, asset manifest with placement, alt text, and data source. Gate 3.5.
• Phase 4: Scientific Validation — hallucination scan, claim traceability, logic validation. Gate 4; failures loop to Phase 3.
• Phase 5: Structure & Proofread — grammar/spelling, readability to the content-type target (±0.5 grade), brand terminology and style. Gate 5.
• Phase 6: SEO/GEO — keyword placements (title, first 100 words, ≥2 H2s, conclusion, meta description), meta tags, URL slug, AI-answer-engine readiness, structure manifest. Density is advisory (~1–2%), not a gate. Gate 6.
• Phase 6.5: Humanizer — human-expert grounding pass, 43-pattern AI-telltale removal (incl. detector-signal patterns 36-43), content-derived variation (burstiness advisory), brand personality, SEO-placement preservation validated against the structure manifest. Gate 6.5.
• Phase 7: Reviewer — 5-dimension weighted scoring per config/scoring-thresholds.json; approve ≥7.0 (industry-adjusted), loop 5.0–6.9, human review <5.0. Gate 7.
• Phase 8: Output — .docx generation with appendices, dual-copy save, optional Drive upload, tracking update. Gate 8.

If a phase loops back: the system shows which phase failed, why, and what it's fixing. Loops are automatic — you don't need to do anything unless it escalates to human review.

Output Example

Every pipeline run ends with a Completion Card showing scores, stats, and delivery status. This card is mandatory — it's shown in the conversation AND added as an appendix in the .docx file.

Example Completion Card (SYNTHETIC EXAMPLE — fabricated for illustration; never reuse these numbers):

CONTENTFORGE — COMPLETION CARD

Content:  "AI in Healthcare: Emerging Trends" | AcmeMed | Article | ✅ APPROVED

Quality Score: 9.2/10 (Grade A+)
  Content Quality:    9.5/10 ✅
  Citation Integrity: 9.0/10 ✅
  Brand Compliance:   9.5/10 ✅
  SEO Performance:    8.8/10 ✅
  Readability:        9.0/10 ✅

Content Stats:
  Words: 1,947 (target 1,500-2,000) ✅ | Citations: 14 sources ✅
  Keyword placements: all critical positions ✅ | Readability: Grade 11.2 ✅
  Burstiness: 0.78 (advisory) | AI Patterns: 0 remaining ✅ | Hallucinations: 0 ✅

SEO Package:
  Meta Title: 58 chars ✅ | Meta Description: 152 chars ✅
  Internal Links: 4 applied | Feature Image: generated (user-approved)

Pipeline: 0 loops | Guardrails: verified | Run: {run_id}

Delivery:
  .docx: ✅ Generated
  Local: ✅ ~/Documents/ContentForge/AcmeMed/AI-in-Healthcare-Emerging-Trends_v1.0.docx
  Drive: ✅ uploaded (if configured) | Tracking: ✅ updated

Next: /contentforge:publish | /contentforge:social-adapt | /contentforge:translate | /contentforge:cf-variants

The orchestrator MUST append three deficiency/advisory lines to every generated Completion Card (omitted from the synthetic example above only because their content is run-specific and often conditional — they sit immediately adjacent to that fenced example by design; do not skip them):

• Internal linking: {deep_links} deep / {homepage_links} homepage links (source: {inventory_source}){IF homepage-only: " — ⚠ HOMEPAGE-ONLY INTERNAL LINKING: deep service pages exist but are not linked"}
• AI-detectability (advisory): {advisory_rating} — {flag_count} signals flagged (details in Quality Appendix; never a publish gate)
• Structural tells (advisory): {structure_overall} — review sheet at {phase-6.5-review-sheet.html}; Tier-2 structure scan (StoryScope-derived), advisory and never a publish gate
• Needs human review: {IF visual manifest has human-review flags: "⚠ {n} visual element(s) need SME sign-off — see visual manifest"}{IF placeholder links: " · ⚠ {n} placeholder link(s) need URLs"}

{deep_links}, {homepage_links}, and {inventory_source} are read from the Phase 6 SEO scorecard's Deep-link coverage: deep_links=N homepage_links=M inventory_source=... line (never from the docx JSON — that JSON's inline_links_internal/inline_links_outbound counters are for the docx appendix, not the card). The AI-detectability line's rating comes from the Phase 6.5 Humanization Report §8 (AI-TELL SCAN), produced by scripts/text-metrics.py --ai-tell-scan: a deterministic LOW/MODERATE/HIGH rating, advisory only and never a publish gate. The human-review line's visual-element flags already exist in the Phase 3.5 visual manifest; the placeholder-link count comes from Phase 8 output. Under Delivery, add a Scorecard: line with the local path of the page built in Phase 8 (scorecard.html, plus the audit state it shows).

Content Types & Specifications

Readability is gated at ±0.5 grade of the content-type target (verified via text-metrics.py). Where the table gives a range, the target is its midpoint.

Video Script is duration-driven, not word-count-driven. Gate 3 checks the total dialogue word budget for the requested duration profile in templates/content-types/video-script-structure.md (30s → 60-75 words, 60s → 120-150, 3min → 360-450, at 120-150 words per minute), not a fixed range, and every scene must carry dialogue + on-screen text + B-roll + music/SFX. Do not apply the ±10% article word-count rule to it.

Brand Profile Setup

Before using ContentForge, create a brand profile:

/contentforge:cf-style-guide

Provide your brand name, industry, voice guidelines (or share existing documents/URLs), and ContentForge generates the profile JSON automatically.

Alternatively, copy config/brand-registry-template.json and fill in manually.

Canonical profile location: ~/.claude-marketing/{brand-slug}/Brand-Guidelines/{BrandName}-brand-profile.json, where the brand slug is lowercase alphanumerics + hyphens. Resolution order: local file first, then Drive cache (Cowork).

Brand Profile Includes:

• Voice & Tone (authoritative, conversational, technical, witty)
• Terminology (approved terms, banned phrases)
• Style Guide (formatting preferences, citation style)
• Guardrails (topics to avoid, compliance requirements)
• Industry Context (Pharma, BFSI, Healthcare, Legal)
• Personality Profile (authoritative, conversational, technical, witty)

Brand profiles are cached (SHA256 hash) so repeat runs skip re-parsing.

See the User Guide for detailed setup instructions.

Quality Assurance

Three-Layer Fact Verification

1. Phase 2 (Fact Checker): URL verification, claim validation
2. Phase 4 (Scientific Validator): Hallucination detection
3. Phase 7 (Reviewer): Final citation integrity scoring

Feedback Loop Management

• Max 2 loops per edge (e.g., Phase 4 → Phase 3, or Phase 7 → Phase X)
• Max 5 loops total per run before human escalation
• Loop counts are recorded in run.json via checkpoint-manager.py loop and survive resume.

Human Review Escalation

Content is flagged for human review if:

• Quality score <5.0/10 (per config/scoring-thresholds.json)
• Critical brand violations detected
• Loop limits reached without passing
• User explicitly requests review
• Run executed in No-Brand Mode (Brand Compliance = SKIPPED)

Flagged content is NEVER auto-published.

Integration with Other Skills

Before ContentForge:

• /contentforge:cf-style-guide — Create brand profile if new brand
• /contentforge:content-brief — Generate research-backed content brief with keyword analysis

Instead of ContentForge (for scale):

• /contentforge:batch-process — Queue 10-50+ pieces through the same pipeline

After ContentForge:

• /contentforge:content-refresh — Update content 6-12 months later with fresh data
• /contentforge:cf-variants — Create A/B test headline/hook/CTA variations
• /contentforge:publish — Publish to Webflow or WordPress via MCP
• /contentforge:social-adapt — Transform article into LinkedIn, Twitter/X, Instagram, Facebook, Threads, TikTok, Bluesky, and YouTube Shorts posts
• /contentforge:translate — Translate preserving brand voice (15+ languages)
• /contentforge:cf-video-script — Generate timestamped video scripts from the article
• /contentforge:cf-analytics — Record quality scores for trend tracking

Requirements

MCP Integrations (Optional)

• Google Sheets — Requirement intake for batch processing, quality tracking
• Google Drive — Brand knowledge vault, output .docx storage
• Webflow/WordPress — Direct CMS publishing via /contentforge:publish

Run /contentforge:cf-integrations to check your connector status. Run /contentforge:cf-connect <name> for setup guides.

Environment

• Claude Code or Cowork (latest version)
• Internet connection for Phase 1 web research — or --sources= in No-Web Mode

Troubleshooting

Hitting an error or an unexpected pipeline outcome? Read `references/troubleshooting.md` (in this skill's directory) for the documented failure modes — missing brand profile, quality score <5.0 after loops, max loops exceeded, pipeline appears stalled, empty guardrails — and the per-phase "what you'll see" reference table.

Example Workflow

For a full synthetic end-to-end walkthrough (brand setup through publish), read `references/example-workflow.md` (in this skill's directory). This is a separate illustrative scenario from the Completion Card above — never reuse its numbers.

Limitations

• Sequential phases — the pipeline is strictly ordered; each gate consumes the previous phase's artifact
• Depth takes time — the pipeline cannot be rushed without compromising quality (use --title and --sources to shave the interactive steps)
• Best with brand profile — No-Brand Mode works but the Brand Compliance dimension is SKIPPED and the run is flagged for manual review

Related Skills

• [/contentforge:batch-process](../batch-process/SKILL.md) — Queue 10-50+ pieces through the same pipeline
• [/contentforge:content-refresh](../content-refresh/SKILL.md) — Update old content with fresh data
• [/contentforge:cf-variants](../cf-variants/SKILL.md) — A/B test headline/hook/CTA variations
• [/contentforge:cf-analytics](../cf-analytics/SKILL.md) — Track quality scores and performance
• [/contentforge:social-adapt](../cf-social-adapt/SKILL.md) — Transform article into social media posts
• [/contentforge:publish](../cf-publish/SKILL.md) — Publish to Webflow/WordPress
• [/contentforge:translate](../cf-translate/SKILL.md) — Translate preserving brand voice
• [/contentforge:content-brief](../cf-brief/SKILL.md) — Generate research-backed content briefs

<!-- Version, agent count, and asset counts are pulled live by /contentforge:cf-help from scripts/plugin-metadata.py. Do not bake version strings into skill bodies -- they drift out of sync every release. The canonical source of truth is .claude-plugin/plugin.json + the agents/ + skills/ directories. -->

Pipeline: 10 phases plus Step 0.5 (Title Curation); 10 quality gates. Phase agents are defined in agents/*.md and enumerated by scripts/plugin-metadata.py --section pipeline. Post-pipeline agents include Batch Orchestrator, Social Adapter, and Translator.

Quality target: composite Reviewer score ≥7.0 to pass (industry-adjusted per config/scoring-thresholds.json); max 2 loops per edge, 5 total; three-layer verification (Fact Checker → Scientific Validator → Reviewer).