Docs CI

Docs CI Skill — validate docs like code

Builds the pipeline that guards the docs, not the docs themselves. Output: GitHub Actions workflow + drift detection script + the docs/docs.yaml manifest convention.

Input

$ARGUMENTS

The docs.yaml manifest (the drift-detection contract)

Written by every skill in the docs suite; consumed by this skill's checks:

# docs/docs.yaml — doc ↔ code mapping
docs:
  - path: docs/ARCHITECTURE.md
    covers: ["src/**"]          # code paths this doc describes
    last_reviewed: 2026-07-27   # last human/agent review date
  - path: docs/api/openapi.yaml
    covers: ["src/api/**", "src/routes/**"]
    last_reviewed: 2026-07-27
  - path: docs/ops/runbooks/
    covers: ["deploy/**", "monitoring/**"]
    last_reviewed: 2026-07-27
review_max_age_days: 90

Stale verdict: the latest commit under covers is newer than last_reviewed, or the review age exceeds review_max_age_days.

Checks it installs (pick per project)

CHANGELOG automation note: if commits use the [type] title format (rules/git-workflow.md), that is not conventional commits, so git-cliff needs a custom parser (commit_parsers) configuration.

Procedure

1. Diagnose the project: which docs/specs exist (docs/, openapi.*, mermaid blocks, docs site generator)
2. Install only checks that match what exists — no spectral gate for a project without OpenAPI
3. Create/update docs/docs.yaml (scan existing docs to draft covers — include comments so users can refine)
4. Create {project}/scripts/check-docs-freshness.sh — copy the template templates/check-docs-freshness.sh into the target project's {project}/scripts/
5. Create .github/workflows/docs-ci.yml (only the needed jobs from templates/docs-ci.yml) — the trigger branch is fixed to main, so adjust to the branching strategy (add develop if it is in use)
6. Run once locally and report: bash scripts/check-docs-freshness.sh

Harness integration (with this plugin's other components)

• TTH mode: hooks/docs-sync.sh queues changed files into .docs-queue/ per completed story → ralph-loop spawns docs-writer. docs-ci is the final layer that re-verifies in CI
• /docs sync command: report stale docs from docs.yaml → delegate updates to the matching docs-* skill

Constraints

• Create only workflows/scripts/docs/. Never modify app source
• Checks requiring uninstalled tools: continue-on-error or conditional (if: hashFiles(...))
• If a CI workflow already exists, add a separate docs-ci.yml — never overwrite