Docs Forge

On first invocation, read references/orchestrator.md and follow its welcome protocol.

Docs Forge turns a code change into the documentation that must travel with it. It owns the content, wording, placement, and freshness checks for PR bodies, PR comments, README/catalog docs, product docs, ADRs, changelog notes, and linked ticket summaries.

Boundary: Docs Forge writes and verifies documentation. Repo Ops decides whether the repository is clean enough to open the PR. Git Ops creates the branch, commit, push, and PR after these gates pass.

Command Reference

DOCS FORGE COMMANDS

  /oc-docs                 Show this menu
  /oc-docs pr              Generate the PR documentation packet
  /oc-docs readme          Refresh README/catalog docs affected by this change
  /oc-docs standardize     Normalize docs frontmatter, headings, owners, links
  /oc-docs upkeep          Run freshness and drift review across docs
  /oc-docs verify          Verify the PR docs packet is present and current

  /checkpoint              Show oc-docs-forge checkpoint

Every-PR Contract

Every PR must contain Docs Forge output in at least one visible surface:

1. The PR body, for normal documentation packets.
2. A PR comment with marker <!-- opchain:oc-docs-forge:pr-docs -->, when the documentation packet is too long for the body.
3. Both the body and a comment, when the body needs a compact summary and the comment carries migration notes, screenshots, large tables, or generated docs.

The PR body must always include a ## Documentation section. If no user-facing documentation changed, say so explicitly and explain why. Silence is not a pass.

Read references/pr-documentation-packet.md before generating or verifying PR documentation.

/oc-docs pr

Inputs:

• git diff --stat and changed file list.
• Commit log against the base branch, when available.
• Relevant checkpoints from oc-app-architect, oc-reverse-spec, oc-code-auditor, oc-bug-check, oc-release-ops, oc-api-dev, oc-stack-forge, and oc-repo-ops.
• Existing README, docs, ADRs, changelog, API docs, product docs, and catalog pages touched by the change.
• Linked ticket or PR draft context, when oc-git-ops provides it.

Outputs:

• A PR body fragment containing ## Documentation.
• Optional PR comment body with stable marker.
• File edits for affected README/catalog/product docs.
• A checkpoint containing the packet summary, surfaces updated, and verification status.

Required PR body fragment:

## Documentation

**Generated by:** oc-docs-forge
**Docs changed:** [README / product docs / ADR / changelog / API docs / none]
**Reader impact:** [What a reviewer or user needs to know]
**Follow-up docs:** [None / ticket ids / deferred PR comment marker]

When the implementation changes behavior, setup, commands, env vars, API contracts, screenshots, release surfaces, skill catalogs, or user workflows, Docs Forge must either update the owning doc file or put a precise follow-up in the PR body/comment. “No docs needed” is valid only with evidence.

/oc-docs readme

Refresh README and catalog docs from source of truth, not by hand-copying stale tables. For Opchain skill catalogs:

• Inventory skills/*/SKILL.md.
• Compare against skills/README.md, site catalog output, and registry flags.
• Add missing skills and remove entries for deleted skills.
• Keep role text compact and user-facing.
• Record the source command or inventory in the checkpoint.

/oc-docs standardize

Normalize docs to the local standard:

• Required frontmatter or metadata.
• Owner, lifecycle, last reviewed date, and breaking-change policy where the local doc family uses them.
• Stable headings and section order.
• Internal links that resolve.
• Generated-file notices where applicable.
• No contradictory instructions across sibling docs.

/oc-docs upkeep

Run a wider freshness pass:

• Find stale READMEs, orphan docs, broken anchors, TODO placeholders, old screenshots, old release names, and references to deleted files.
• Compare docs against actual commands, package scripts, config names, and generated catalogs.
• Open or draft PM follow-up tickets for doc work that is real but out of scope for the current PR.

/oc-docs verify

Pass only when:

• A current PR docs packet exists in the checkpoint.
• The PR body fragment includes ## Documentation.
• Any required README/product docs edits are present in the worktree or a follow-up is explicitly listed.
• The packet reflects the current diff, not an older commit.
• Links and referenced files exist.

Failure blocks oc-repo-ops verify, which blocks oc-git-ops from opening the PR.

Checkpoint Integration

Location: {project-dir}/.checkpoints/oc-docs-forge.checkpoint.json

Write on every /oc-docs pr, /oc-docs readme, /oc-docs standardize, /oc-docs upkeep, and /oc-docs verify run.

{
  "skill": "oc-docs-forge",
  "phase": "pr-docs",
  "status": "complete",
  "progress_summary": "Generated PR docs packet and refreshed skills/README.md.",
  "context_primer": {
    "key_decisions": [
      "Every PR requires a Documentation section in the PR body.",
      "Long docs packets move to a PR comment with marker opchain:oc-docs-forge:pr-docs."
    ],
    "generated_files": [
      "skills/README.md",
      "/tmp/pr-description.md"
    ]
  },
  "skill_state": {
    "pr_body_fragment": "## Documentation\n...",
    "pr_comment_marker": "<!-- opchain:oc-docs-forge:pr-docs -->",
    "docs_changed": ["skills/README.md"],
    "docs_not_changed_reason": null,
    "follow_up_docs": [],
    "verified_for_sha": "abc123"
  }
}

Cross-Skill Reads