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.

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>
   

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

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

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

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

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

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

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

Phase	subagent_type	Reads (paths)	Writes (artifact)	Quality gate (orchestrator-verified)	Gate-FAIL loop target
0.5	— inline (orchestrator)	brand profile, requirements	phase-0.5-title.txt	User-confirmed title (or --title bypass) — user checkpoint, not a numbered quality gate	Regenerate title options
1	contentforge:researcher	phase-0.5-title.txt, requirements, brand profile	phase-1-research.md + phase-1-link-inventory.json (the verified Internal-Link Inventory as data rows — v4.0)	Gate 1: 12–15 sources collected; ≥10 citable; ≥5 with reliability ≥8; differentiated angle documented; Client Site Reconnaissance complete; ≥3 verified deep brand URLs when the brand has a website	Re-run Phase 1 with broader search
2	contentforge:fact-checker	phase-1-research.md	phase-2-factcheck.md	Gate 2: ≥80% of claims verified; zero UNRESOLVED flags (flagged claims must be removed or re-sourced); ≤3 unverified tolerated; all cited URLs live	Phase 1 (find alternative sources)
3	contentforge:content-drafter	phase-0.5-title.txt, phase-1-research.md, phase-2-factcheck.md, brand profile, requirements (+ telemetry advisories when the floor is met — see "Lifecycle steps" below)	phase-3-draft.md	Gate 3: body_word_count ±10% of target — not word_count, which includes the reference list (a live run drafted a 1,779-word body under a 1,200-word target while word_count read 2,887). What body_word_count counts, stated so nobody has to invent a convention: the prose a reader reads, plus H2/H3 headings. It excludes the H1, the bold **Key:** value metadata block, horizontal rules, HTML comments, [VISUAL-PLACEHOLDER: …] annotation lines (production instructions for Phase 3.5 that never publish), block image embeds and the italic figure-caption line directly beneath each (figure furniture — on a live run three approved charts' alt texts and captions moved the measured body from 1,274 gate-passed words to 1,501, which would have failed the final audit for having its figures described properly), and every trailing reference/appendix section. This matters: on one live draft the two defensible readings gave 1,390 (FAIL) and 1,223 (PASS) for the same file — a gate whose verdict depends on an unstated convention is not a measurement. Do not hand-count; read the field; all outline sections covered; ≥1 citation per 300 words	Re-run Phase 3
3.5	contentforge:visual-asset-annotator	phase-3-draft.md, phase-2-factcheck.md, phase-1-research.md (SERP visual patterns)	phase-3.5-visuals.md (contains the ANNOTATED draft — the operative article from here on) + phase-3.5-visual-manifest.json	Gate 3.5: every chart traceable to a verified statistic; manifest complete (placement, alt text, data source); human-action TODOs marked	Re-run Phase 3.5
4	contentforge:scientific-validator	phase-3-draft.md, phase-3.5-visuals.md, phase-3.5-visual-manifest.json, phase-2-factcheck.md, phase-1-research.md (the Verified Outline, required by its Step 6.1)	phase-4-validation.md + phase-4-fixes.json (the fix ledger — required whenever the report names a correction, empty items is valid)	Gate 4: zero hallucinations; every claim traceable to a cited source; logic consistent; fix-ledger.py validate exits 0 and every correction in the report appears in the ledger	Phase 3 (with the specific claims to fix)
5	contentforge:structurer-proofreader	phase-3.5-visuals.md (the ANNOTATED draft — the operative article text, with the VISUAL anchors that must survive), phase-3-draft.md (pre-annotation reference), phase-4-validation.md, phase-4-fixes.json, brand profile	phase-5-structured.md	Gate 5: fix-ledger.py verify reports zero unresolved blocking items (HARD); zero grammar/spelling errors on re-scan; readability within ±0.5 grade of the content-type target (text-metrics.py); brand terminology compliance	Re-run Phase 5
6	contentforge:seo-geo-optimizer	phase-5-structured.md, phase-1-research.md (Internal-Link Inventory), phase-3.5-visual-manifest.json (feature image), brand profile, requirements (keyword)	phase-6-seo.md + phase-6-structure-manifest.json	Gate 6: keyword PLACEMENTS present — title, first 100 words, ≥2 H2s, conclusion, meta description (density is advisory, ~1–2%); meta title + description generated; all internal-link URLs verified live (HARD); ≥2 deep brand links when site known (scored+flag)	Re-run Phase 6
6.5	contentforge:humanizer	phase-6-seo.md, phase-6-structure-manifest.json, phase-4-fixes.json (the applied-fix protected set), brand profile, source-draft.md (when present)	phase-6.5-humanized.md (article body only — authorship.py measures this file) + phase-6.5-report.md + phase-6.5-review-sheet.html + phase-6.5-pattern-hits.json (per-pattern fire counts for telemetry.py — v4.0) + phase-6.5-authorship.json (only when source-draft.md exists)	Gate 6.5: grounding pass complete; 43-pattern catalog; GEO structure preserved; keywords preserved; AI-tell scan reported (advisory); burstiness advisory; with an author draft: authorship.py exits 0 — zero author sentences rewritten or dropped (NOT advisory); fix-ledger.py verify does not exit 3 — a style pass may not undo an applied accuracy correction (NOT advisory)	Re-run Phase 6.5 with the violated constraint stated (incl. structure-manifest mismatch, authorship violations, or a regressed ledger fix)
7	contentforge:reviewer	ALL prior artifact paths, phase-4-fixes.json, brand profile, requirements, config/scoring-thresholds.json	phase-7-review.json (includes publication_status + fix_ledger) + phase-7-fix-ledger.json (the verify payload, written by the script as UTF-8 so the reviewer copies bytes rather than scraping a console) + phase-7-review-pre-remediation.json (re-review mode only: the prior review, preserved before re-scoring — the old score is evidence, not garbage)	Gate 7: reviewer decision tree per config/scoring-thresholds.json — approve ≥7.0 (industry-adjusted); all dimension minimums met; dead internal link = hard FAIL; homepage-only linking caps the sub-score and surfaces on the Completion Card; fix_ledger copied from fix-ledger.py verify, never re-derived by hand	5.0–6.9 → loop to responsible phase (recorded as pending_rework); <5.0 → human review, halt
8	contentforge:output-manager	phase-6.5-humanized.md, phase-6.5-report.md, phase-7-review.json, phase-3.5-visual-manifest.json, phase-6-seo.md (SEO Scorecard for Appendix A), run.json, phase-6.5-authorship.json (when present)	phase-8-output.json + .docx	Gate 8: .docx generated; all four appendices present — A (SEO Scorecard), B (Quality Scorecard), C (Production Details), D (Internal Link Map) — matching appendices_present: 4 in config/scoring-thresholds.json; delivery location verified. This row previously said A/B/C while the config required 4, and this file states that the config wins where they disagree — so a Phase 8 emitting only A/B/C would have passed the documented gate and failed the configured one. Also: the body must carry no production scaffolding and must anchor every generated asset — text-metrics.py reports residual_scaffolding.clean: true and visual_markers.ids covering every manifest asset with status: generated. One run delivered three raw [VISUAL-PLACEHOLDER: …] lines to the reader and embedded none of its three valid charts, because Phase 3.5's marker replacement never landed and nothing downstream compared the two. And: fix-ledger.py verify runs here and sets publication_status. Unresolved blocking corrections do not stop the .docx being produced — they stop it being called ready: DRAFT- filename prefix, publication_blockers in phase-8-output.json, and the blocked status in the tracking row	Re-run Phase 8; if generation still fails, save markdown + reports locally and report the failure

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. The verdict lands in run-audit.json inside the run directory.

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.

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