docs(workflow-builder): add MkDocs pages + nav for the skill

[alirezarezvani]

Summary

Documentation pass for the workflow-builder skill — generates and wires up its GitHub Pages so it shows up in the docs site.

• Generated 3 pages via scripts/generate-docs.py:
  • docs/skills/engineering/workflow-builder.md
  • docs/agents/cs-workflow-architect.md
  • docs/commands/cs-workflow-build.md
• Wired into mkdocs.yml nav: Engineering - POWERFUL (skill), Agents (cs-workflow-architect), Commands (/cs:workflow-build).
• Updated section index pages (skills/engineering, agents, commands).
• Build verified clean: mkdocs build succeeds, all 3 pages render, 551 HTML pages total. The only warnings are pre-existing and unrelated (cs-seo-audit link, grill-with-docs CONTEXT/ADR-FORMAT links).

Counts unchanged

Aggregate skill/domain counts were not touched — workflow-builder was already absorbed into dev's 338 skills / engineering-advanced (78) header when it merged before the research-ops counting pass. No double-counting.

Out of scope (intentionally excluded)

Re-running the Codex sync only produced unrelated duplicate-slug symlink drift (review/run/status re-pointing between equally-valid plugins) — workflow-builder was already in the codex/gemini indexes. I reverted that noise to keep this PR scoped to docs.

Test plan

• mkdocs build exits clean; the 3 new pages build to HTML
• All nav .md targets resolve on disk (0 missing)
• New pages have valid YAML frontmatter
• The 3 skill scripts still pass --help

https://claude.ai/code/session_01Q1kXbgMRodzhdTpgbCqVgx

---

Generated by Claude Code

[claude]

PR #767 Review — docs(workflow-builder): MkDocs pages + nav

Scope: Documentation-only pass (3 new pages + nav wiring). No Python scripts or plugin manifests changed.

---

Summary

The docs pages are well-structured and consistent with existing conventions. Navigation wiring in mkdocs.yml is clean. Count bumps (agents 89→90, commands 83→84, engineering-powerful 73→74) are accurate. One issue needs fixing before this leaves DRAFT.

---

Issues

🔴 Must-fix — Malformed meta description in docs/agents/cs-workflow-architect.md (line 3)

description: "Workflow-architect persona. Opens every workflow-creation session with
the intake question set, infers-and-proposes when the user is vague (never. Agent-native
orchestrator for Claude Code, Codex, Gemini CLI."

(never. is a mid-parenthetical truncation artifact — the closing ) is missing and the clause is cut off mid-thought. This is the only description across the three pages that ends at a clearly broken syntax boundary (the others truncate at word/sentence ends). Fix by rewriting the description so it truncates naturally:

description: "Workflow-architect persona. Design-first orchestrator that runs intake,
recommends a topology, scaffolds the .js file, and validates before running.
Agent-native skill for Claude Code, Codex, Gemini CLI."

---

🟡 Pre-existing, not introduced here — noted for completeness

Truncated description in docs/skills/engineering/workflow-builder.md (line 3):
"...for Claude Code's Workflow tool. Use when a user wants." — "Use when a user wants." is a sentence fragment, but the same truncation artifact exists in caveman.md ("Use.") and handoff.md ("issues.") — this is a generate-docs.py template issue across the whole docs site, not specific to this PR.

2-claude-skills repo URL in docs/commands/cs-workflow-build.md (line 10):
href="https://github.com/alirezarezvani/2-claude-skills/..." — consistent with all 46 existing command pages (checked: cs-handoff.md, cs-caveman.md, etc.). Pre-existing repo-wide issue, not introduced here.

Title/H1 uses /cs-workflow-build (hyphen) vs actual command /cs:workflow-build (colon):
Matches the established pattern for /cs-handoff, /cs-grill-me, etc. Consistent, even if technically inconsistent with the real command syntax.

---

Testing Notes

Per the PR description, mkdocs build was verified clean (551 HTML pages, 3 new pages rendered). The 3 Python scripts were verified passing --help. Both checks look complete.

Yamllint was not re-run in this review pass due to tooling approval flow — the mkdocs.yml nav entries added are syntactically consistent with surrounding entries (verified via grep).

---

Verdict

Fix the (never. truncation in cs-workflow-architect.md description, then this is ready to move from DRAFT → ready for review. Everything else is clean.