wiki-orchestrator

Wiki Orchestrator

Route bulk/multi-page wiki edits through the 7-stage pipeline below. Single-page edits use tools/wiki-write.sh directly. Wrong skill? Links → link-verification · Facts → wiki-debunker · Drift → wiki-verify · Secrets → wiki-secret-audit · Full refactor → wiki-refactor. Background: rationale.md.

When to Use

• When asked to document something in the wiki, publish content, or run bulk wiki updates
• Triggered by: document X in wiki, wiki:create, wiki:update, wiki:publish, bulk wiki update
• Single-page edits can skip directly to tools/wiki-write.sh. This skill is for multi-page or pipeline-driven writes.
• Wrong skill? Links → link-verification · Facts → wiki-debunker · Drift → wiki-verify · Secrets → wiki-secret-audit

Step 0 — Load adapter (before any write)

source ~/.codex/.env 2>/dev/null || true
: "${WIKI_PLATFORM:?set WIKI_PLATFORM in ~/.codex/.env (e.g. outline)}"
cat "$HOME/.codex/superpowers-plus/skills/wiki/_adapters/${WIKI_PLATFORM}.md"

If WIKI_PLATFORM is unset and no adapter loads → STOP. Do not write.

The 7-stage pipeline (BLOCK gates halt; fix, resume from failed stage)

#	Stage	Gate	Command
1	De-dup	WARN	tools/wiki-read.sh search "<topic>" --limit 5
2	Generate	—	Apply formatting rules below
2.5	Coherence	ADVISORY	use-skill wiki-content-coherence
3	Links	BLOCK	use-skill link-verification
4	Secrets	BLOCK	use-skill wiki-secret-audit
4.5	Language	BLOCK	node tools/language-scanner.js draft.md (exit 0=PASS, 1=BLOCK, 2=ABORT, 127+=ABORT)
5	Slop	ADVISORY	use-skill eliminating-ai-slop
5.5	Structure	BLOCK	node tools/wiki-markdown-validate.js draft.md
6	Facts	WARN	use-skill wiki-debunker
7	Publish	—	tools/wiki-write.sh {create|update|move} …

Stage 4.5 — Language gate contract:

• Exit 0: PASS — proceed
• Exit 1: BLOCK — profanity found; replace flagged terms (or wrap in [F-WORD]/[EXPLETIVE]/[REDACTED: reason]), re-run until exit 0
• Exit 1 with MODULE_NOT_FOUND on stderr: ABORT — scanner file missing, not profanity found
• Exit 2: ABORT — invocation error; fix and retry; do NOT infer PASS
• Exit 127+: ABORT — node not on PATH; install Node.js; do NOT infer PASS

Combined-invocation note (when implementing as bash): If Stages 4 (secret scan) and 4.5 (language scan) both read from a shared temp file ($WIKI_TMP), run them in a single shell invocation — splitting across two Bash calls destroys $WIKI_TMP via EXIT trap. This applies to bash implementations; the AI skill dispatch (above) is unaffected.

Stage 7 — write via tools/wiki-write.sh

tools/wiki-write.sh create --parent "$PARENT_UUID" --title "$TITLE" --content draft.md
tools/wiki-write.sh update --doc    "$DOC_UUID"                     --content draft.md
tools/wiki-write.sh move   --doc    "$DOC_UUID"    --parent "$NEW_PARENT_UUID"

Exit: 0 ok+verified · 1 scope · 2 env/arg · 3 API · 4 verify failed. Never create a root page. On exit 1 stop and ask; do not retry.

Content formatting (Stage 2)

Rule	Action
H1 in body	Drop — platform renders title
Raw HTML /   / > [!info]	Remove; breaks API round-trip
[ ] or   in table cells	Use Yes/No or ✓/✗
Code blocks	Always tag language
4+ H2/H3 outside fences, toc_behavior=manual, no TOC	Insert adapter toc_syntax

Pre-write checklist

1. tools/wiki-read.sh search "<title>" --limit 5 (dedupe)
2. tools/wiki-read.sh get "<id-or-slug>" (fetch state / verify parent)
3. Apply Content formatting rules to draft
4. node tools/wiki-markdown-validate.js draft.md → exit 0 or fix
5. tools/wiki-write.sh {create|update} … → exit 0 or stop

Pre-delete: backup first

mkdir -p _deleted_backups && tools/wiki-read.sh get "$DOC_ID" \
  > "_deleted_backups/$(date +%F)_${DOC_ID}.json" \
  || { echo "backup failed, refusing delete"; exit 1; }
# only now invoke the adapter's delete/archive operation

Failure modes

Failure	Recovery
Pipeline used for single-page edit	Use tools/wiki-write.sh directly
Skipped a BLOCK stage	Restart pipeline from that stage
wiki-write.sh exit 1	Stop; ask user
wiki-write.sh exit 4	Re-run Stage 5.5 on fetched body, fix, retry

Philosophy, rationalizations, companion-skill list: rationale.md.