Chronos

Chronos — Documentation Timekeeper

5 AI agents for documentation integrity. Each agent is a focused skill invoked by the Chronos orchestrator.

What it does

Chronos audits project documentation for:

• Duplicates — documents with high similarity (Censor)
• Broken links — references to non-existent files (Censor)
• Missing required docs — mandatory files per classification level (Dewey)
• Orphans — documents with no inbound references (Dewey)
• Classification — document type: L1 Contracts → L6 Auxiliary (Dewey + Canon)
• Stale data — dates older than threshold (Veles)

Agents

Usage

# Basic audit (duplicates + links only)
chronos --path .

# Standard: check + classify (Censor + Dewey + Canon)
chronos --path . --preset standard

# Full Pantheon: all 5 agents
chronos --path . --preset full

# JSON output for CI
chronos --path . --output json --output-file report.json

# Fail on critical findings
chronos --path . --fail-on critical

# Single agent
chronos --path . --agent censor

Presets

Document Hierarchy (L1–L6)

L1: Contracts        — Machine truth (OpenAPI, AsyncAPI, JSON Schema)
L2: Product Canon    — Human truth (VISION, PRD, ROADMAP, FEATURES)
L3: Engineering Canon— Implementation truth (ARCHITECTURE, ADR, SAGA)
L4: Derived          — Synthesized (REFERENCE, TEST_CASES, DEV_GUIDE)
L5: Artifacts        — Generated (API docs, changelogs, diagrams)
L6: Auxiliary        — Supporting (README, CONTRIBUTING, templates)

Each level has required files. Dewey enforces presence; Canon validates L1→L3 consistency.

Output Format

# Docs Audit Report

**Project:** /path/to/project
**Total docs:** 24
**Preset:** standard

| Severity | Count |
|----------|-------|
| Critical | 1 |
| Warning  | 3 |
| Info     | 2 |
| **Total**| **6** |

### CRITICAL

**File:** docs/API.md:42
**Issue:** Endpoint GET /users documented as Deprecated, but contract shows Active.
**Fix:** Update docs/API.md to match OpenAPI contract.

### WARNING

**File:** docs/ARCHITECTURE.md
**Issue:** Orphan document — no inbound references from L2/L3.
**Fix:** Link from PRD or add to REFERENCE.md.

### INFO

**File:** docs/DEV_GUIDE.md
**Issue:** Last updated 2024-01-15 (stale >180 days).
**Fix:** Review and update or archive.

Triggers

• check documentation / docs audit / audit docs
• docs integrity / documentation health
• find duplicates in docs / duplicate docs
• broken links / broken references
• stale documentation / outdated docs
• classify docs / document classification
• orphan docs / unreferenced documents
• validate docs / doc quality / docs lint
• chronos

Installation

pip install chronos

Or run directly:

python -m chronos --path .

Project Structure

skills/chronos/
├── SKILL.md              # This file
├── src/chronos/          # Python package
│   ├── __init__.py
│   ├── cli.py            # Entry point
│   ├── orchestrator.py   # Chronos agent
│   ├── agents/
│   │   ├── censor.py     # Duplicates + links
│   │   ├── dewey.py      # Classification L1-L6
│   │   ├── veles.py      # Staleness + metrics
│   │   └── canon.py      # Cross-ref validation
│   ├── models.py         # Data classes
│   └── utils.py          # Helpers
├── tests/                # 67 pytest tests
├── presets/              # JSON presets
│   ├── minimal.json
│   ├── standard.json
│   └── full.json
└── pyproject.toml

Configuration

Create .chronos.yml in project root:

path: "."
preset: "standard"
fail_on: "warning"
output: "markdown"
thresholds:
  duplicate_similarity: 0.85
  stale_days: 180
  required_levels:
    L1: ["contracts/openapi.yaml"]
    L2: ["VISION.md", "PRD.md", "ROADMAP.md"]
    L3: ["ARCHITECTURE.md", "ADR/"]
    L4: ["REFERENCE.md"]
    L6: ["README.md", "CONTRIBUTING.md"]
ignore:
  - "node_modules/**"
  - ".git/**"
  - "dist/**"

CI Integration

# .github/workflows/docs-audit.yml
- name: Chronos Docs Audit
  run: |
    pip install chronos
    chronos --path . --preset standard --fail-on warning --output json --output-file chronos-report.json

Verification Gates

Every Chronos run must pass:

1. Structural — output is valid Markdown/JSON
2. Content QA — each finding has file:line, issue, fix
3. Reproducibility — same input → same output (deterministic hashing)

References

• references/CLASSIFICATION.md — L1-L6 taxonomy details
• references/AGENTS.md — Agent prompt templates
• references/CONFIG.md — Full config schema