docs-as-code-lifecycle

name

docs-as-code-lifecycle

description

Use when acting on an existing or in-progress Documentation-as-Code repo — assessing and scaffolding it, authoring or promoting a BRD/PRD/FR/NFR/ADR/Epic/Story/Test artifact, building a traceability matrix, versioning an inter-team API contract, validating frontmatter/links, auditing gaps and drift, or preparing a docs pull request. Routes the request to the right docs-as-code:* command. For a first-time conceptual introduction, defer to the docs-as-code-intro skill.

Docs-as-Code Lifecycle

This skill operationalizes the Track A curriculum: each command automates one stage of the docs-as-code lifecycle. The commands are thin wrappers — the runnable logic lives in scripts/ so every check also runs locally in one bash command (Lesson 5), and Cursor/Codex can reuse the same scripts via AGENTS.md without re-implementing anything.

Lifecycle → command map (docs-as-code:*)

Stage	Command	What it does	Script	Lesson
Learn	docs-as-code:learn	Introduce + teach docs-as-code; walk the curriculum	— (teaching)	1
Onboard	docs-as-code:onboard	Assess a team's maturity → tailored adoption roadmap	docs-init.sh	1
Init	docs-as-code:init	Assess repo readiness, then scaffold product-docs/ + CI	docs-init.sh	3
Migrate	docs-as-code:migrate <source>	Bring a legacy doc (Word/PDF/Confluence) into the structure	docs-new.sh	3
Author	docs-as-code:new <type> <slug>	Create an artifact from its template, frontmatter pre-filled	docs-new.sh	2, 3
Trace	docs-as-code:trace	Build/verify the traceability matrix; gaps, dead links, orphans	docs-trace.sh	3
Contract	docs-as-code:contract new|bump	Create or version an inter-team API contract	docs-contract.sh	3B, 6
Quality	docs-as-code:validate	Frontmatter + Markdown lint + link check (CI-ready)	docs-validate.sh	5
Audit	docs-as-code:audit	Health rollup: gaps + drift + four metrics	docs-audit.sh	1, 5, 6
Workflow	docs-as-code:review	"docs + code + contract in one PR" check + assign reviewers	docs-review-prep.sh	4
Lifecycle	docs-as-code:promote <artifact>	Transition status draft → review → active/deprecated	docs-promote.sh	5
Visualize	docs-as-code:diagram	Render the traceability chains as a Mermaid flowchart	docs-diagram.sh	3
Publish	docs-as-code:publish	Build a static docs site (VitePress/MkDocs) from docs/	— (generator)	5, 6

This skill routes between 13 commands. Five specialist agents go deeper than a command: docs-reviewer (per-PR review), traceability-auditor (whole-repo trace audit), contract-breaking-detector (classify a contract change), migration-planner (sequence a bulk migration), and onboarding-coach (tailor a team's adoption). Three topic skills add depth: docs-as-code-ci-setup, docs-as-code-at-scale, and docs-as-code-metrics.

Principles

• Thin wrapper. Commands orchestrate; the logic lives in scripts/ and is runnable locally (bash "${CLAUDE_PLUGIN_ROOT}/scripts/docs-*.sh", or bash scripts/docs-*.sh from a checkout of this kit). A check you cannot run at your terminal is not done.
• Frontmatter is the source of truth. Traceability, status, and ownership are all read from YAML frontmatter — never from a side database. Required fields are listed in references/frontmatter-schema.md.
• Surface, don't hide. Gaps, drift, and broken links are reported, never silently skipped. A missing Test cell is a coverage hole shown on purpose.
• Cross-tool by design. Claude Code first. AGENTS.md exposes the same scripts/ to Cursor/Codex so there is one implementation, several front-ends.

How to route

Map the user's intent to a command and invoke it. Someone new → docs-as-code:learn. Setting up a repo → docs-as-code:init. Bringing existing Word/Confluence docs in → migrate. Day-to-day authoring → new / trace / contract. Before a release or weekly review → audit. Shipping a change → review → promote. A multi-stage request ("set up docs and add a contract") → sequence: init → new → contract.

To make the gate run on every PR, copy the example CI step examples/nova-superapp/.github/workflows/validate.yml — it calls docs-validate.sh and blocks the merge on failure. Reviewer assignment comes from CODEOWNERS (a contract's consumers are its required reviewers) plus the owner frontmatter field.

Worked example

Every command targets the structure in examples/nova-superapp/ and the templates in templates/product-docs/. All scripts are tested against that example.