Skip to content

Establish Standards and Repository Hygiene

A repository contains Markdown documentation written by multiple contributors. Without clear standards, metadata contracts, and deterministic tooling, documentation drifts and becomes unreliable.

Goal

Establish a predictable documentation system: templates, routing, markup rules, and quality gates that scale with the team.

Steps

  1. Initialize or validate arqix.toml and the documentation structure.
  2. Define the set of supported document kinds (ADR, US, REQ, workflow, persona, unit, glossary).
  3. Create and store templates for each kind (EN source).
  4. Define markup rules for includes and trace markers.
  5. Run fmt and lint over the documentation tree.
  6. Fix violations or adjust rules where they block legitimate use.
  7. Document standards and processes in the handbook (including agent rules).

Outputs

  • Consistent templates and routing rules
  • Deterministic formatting and linting baseline
  • Documented conventions in the handbook
  • A stable foundation for CI and agents

Failure Modes

  • Rules are too strict and block real writing patterns.
  • Templates are missing and contributors start copy-pasting.
  • IDs drift or duplicate due to lack of validation.
  • arqix config validate
  • arqix doc new <kind>
  • arqix fmt
  • arqix lint run
  • arqix trace scan (baseline quality check)

Automation (optional)

  • just: just verify — the daily gate doubles as the hygiene pass