---

name: docs-publish description: >- Land an approved documentation branch on main. Default: push the branch and open a squash PR to main with a rich, artifact-linked body (Summary/Goal/Design/Research/Phases/Verification). Alternative (local): squash-merge into main locally. Confirms before any irreversible/outward step; never targets dev. NOTE: merging to main auto-deploys to production (Geddes) within ~5 minutes — this is the one irreversible, outward step. Final step of the documentation factory. disable-model-invocation: true argument-hint: "[pr (default) | local] [merge]" allowed-tools: Read, Grep, Glob, AskUserQuestion, Bash(git status *), Bash(git branch *), Bash(git log *), Bash(git diff *), Bash(git rev-parse *), Bash(git fetch *), Bash(git push *), Bash(git switch *), Bash(git checkout *), Bash(git merge *), Bash(git add *), Bash(git commit *), Bash(gh pr *), Bash(gh repo *), Bash(.venv/bin/python .agents/factory/bin/meta_status.py *)

docs-publish — ship the branch to main

Open a squash PR to main (default) or squash-merge locally. Merging to main deploys to production within ~5 minutes — there is no staging gate. Always confirm before the irreversible step, and never target dev (CI blocks dev → main anyway; dev is the a11y branch).

Step 0 — status (when requested)

Report the review verdict, commits vs main, and any existing PR (gh pr status). No action.

Step 1 — Pre-flight

• On the feature/|fix/|refactor/ branch, clean tree; resolve {slug}.
• Read kind and review.verdict from TECH.md — STOP if the verdict is not approved (unless the human explicitly overrides). If review flagged a human gate, confirm sign-off happened.
• git fetch origin; flag if the branch is behind main.

Step 2 — Compose PR title + body

• Title: [{kind}] {imperative summary} synthesized from GOAL.md (never Conventional Commits like feat:/docs:).
• Body (link artifacts via SHA-pinned permalinks using git rev-parse HEAD; link, don't quote):
  • Summary — what changed and why (from GOAL).
  • Goal → spec/{slug}/GOAL.md
  • Design → spec/{slug}/PLAN.md
  • Research → spec/{slug}/research/*.md (if present)
  • Phases completed → from the TECH.md FSM (id · name · satisfies R-IDs)
  • Verification → from spec/{slug}/REVIEW.md (build/render/link/nav/a11y results, verdict)
  • 🔧 Harness feedback (only if .venv/bin/python .agents/factory/bin/meta_status.py spec/{slug}/META.md --status open reports open > 0) → a short, collapsed section listing each open finding (id · severity · title), then label the PR: gh pr edit --add-label harness-feedback. Keep it terse (link to META.md for detail) so it doesn't dominate the PR; route them later with /docs-harness. Do not write or resolve findings here.
  • Closes #NN (this auto-closes the issue — main is the default branch)
  • trailing line: 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Step 3 — Confirm with the human (mandatory)

AskUserQuestion: mode (PR vs local), title, and body. This is the last gate before production.

Step 4a — PR (default)

git push -u origin {branch} → gh pr create --base main --head {branch} --title "…" --body-file …. If merge is confirmed: gh pr merge {N} --squash --subject "{title}" --body "…" --delete-branch.

Step 4b — local

git switch main && git pull --ff-only → git merge --squash {branch} → git commit -m "{title}" → git branch -D {branch}. Do not push main unless explicitly asked (a push to main triggers the production deploy).

Step 5 — Report

PR URL / merge result, the squash subject, and the retained spec/{slug}/ artifacts. Remind the human that a merge to main rolls out to docs.rcac.purdue.edu within ~5 minutes.