Skip to content

Getting Started

Jump to bottom
CH-ZHOU-0512 edited this page Aug 3, 2026 · 1 revision

Getting Started

govern-project-docs can be adopted at three levels. Start with the smallest level that solves your problem; automation can be added later without changing the core governance model.

中文概览：可以只安装 Codex Skill、只运行只读审计，或把索引与检查工具完整接入目标仓库。建议先审计，再决定是否改造。

Choose an adoption path

Path Best for Changes the target repository?
Codex Skill Guided audit, migration, taxonomy, and authority design Only when you explicitly approve edits
Read-only audit A fast inventory and risk report No
Runtime integration Persistent indexes, checks, watch mode, hooks, and CI Yes

Install the Codex Skill

Clone the repository into the Codex skills directory.

PowerShell:

git clone https://github.com/CH-ZHOU-0512/govern-project-docs.git (Join-Path $env:USERPROFILE ".codex\skills\govern-project-docs")

macOS or Linux:

git clone https://github.com/CH-ZHOU-0512/govern-project-docs.git "${CODEX_HOME:-$HOME/.codex}/skills/govern-project-docs"

Invoke it by name:

Use $govern-project-docs to audit this repository. Report the authority map,
duplicates, archive candidates, and automation opportunities before editing.

The Skill treats audit, editing, committing, and publishing as separate permissions. Installing it does not authorize repository changes.

Run the read-only audit

Requirements:

  • Node.js 22 or 24;
  • a local checkout of this repository;
  • no npm install or third-party packages.

Human-readable report:

node scripts/audit-docs.mjs --repo /path/to/target-repository

Machine-readable report:

node scripts/audit-docs.mjs --repo /path/to/target-repository --json

The report covers:

  • Markdown counts and documentation categories;
  • missing metadata in active documentation;
  • duplicate non-README titles;
  • large documents and review candidates;
  • broken local links and stale path references;
  • archived or superseded documents outside expected boundaries.

The audit respects ignored directories and never writes to the target repository.

Adopt persistent automation

Copy the four runtime files as a unit into the target repository, normally under scripts/:

Source Suggested destination
assets/runtime/docs-toolkit.mjs scripts/docs-toolkit.mjs
assets/runtime/document-index.mjs scripts/document-index.mjs
assets/runtime/check-doc-governance.mjs scripts/check-doc-governance.mjs
assets/runtime/check-markdown-links.mjs scripts/check-markdown-links.mjs

Then copy and adapt these templates when the repository has no equivalent policy:

Source Suggested destination
assets/templates/docs-governance.config.json scripts/docs-governance.config.json
assets/templates/docs-governance.schema.json scripts/docs-governance.schema.json

Copying is not the design step. Review the target repository's existing instructions, document roots, metadata, generated directories, package scripts, hooks, and CI before enabling checks.

Suggested first rollout

  1. Run the read-only audit and save the findings outside the target tree.
  2. Name one authority for every changing fact that currently has conflicting copies.
  3. Create only the documentation categories the project actually needs.
  4. Move completed or superseded evidence into docs/archive/; do not discard it.
  5. Add metadata to active documents.
  6. Generate the document index twice and confirm identical output.
  7. Add check, governance, and link validation to CI.
  8. Treat local watch mode as convenience, not as the correctness boundary.

A minimal documentation tree

docs/
├── README.md             # compact routing page
├── architecture/         # cross-domain architecture and rationale
├── domains/              # one compact entry point per capability
├── delivery/             # current status and active acceptance
├── governance/           # policies, decisions, risks, security
├── operations/           # deploy, recover, and roll back
├── product/              # product scope and user-facing reference
├── generated/            # derived files; never hand-edit
└── archive/              # completed or superseded evidence

This is a vocabulary, not a mandatory empty-folder template. Omit categories that do not have an authority to hold.

Next steps

govern-project-docs

Clone this wiki locally