alifazl3/dokit

dokit packages DocOS — the Documentation Operating System — as a Claude Code skill. It gives every project the same disciplined documentation layer: a numbered docs/ taxonomy, a template for every document type, naming and lifecycle rules, and a documentation Definition of Done that ties docs to code changes — usable by humans and AI agents alike.

One home for every document

Single source of truth, enforced by structure: the API contract lives in 06-api/openapi.yaml, decisions in 19-decisions/ as ADRs, domain shape in 04-domain/, operational procedures in 23-runbooks/. Nothing is duplicated — everything else links. Every document carries front matter (owner, status, version, last review) and follows one naming convention.

The numbered taxonomy is the default, not a cage: ask Claude for a custom layout and it designs the tree with you and records it in docs/STRUCTURE.md, which later sessions follow. The writing rules — one docs/ tree, single source of truth, indexes, templates, front matter, the Definition of Done — apply in every layout.

The full normative standard (Persian) is in references/standard-fa.md; references/structure.md is the quick folder map.

How it works

1. Scaffold — init_docs.py creates the full docs/ tree with root indexes and a starter README in every section (--minimal for small projects, --with-mobile to include 12-mobile).
2. Write — copy the matching file from templates/ and fill it in; with the skill installed, Claude picks the right template, destination, and front matter for you.
3. Validate — validate_docs.py lints the tree: required files, naming conventions, ADR filename format, front matter statuses, broken links. It exits non-zero on errors, so it drops straight into CI as a docs-lint job.

Install

As a plugin (recommended) — inside Claude Code:

/plugin marketplace add alifazl3/dokit
/plugin install dokit@dokit

This also auto-registers the changelog Stop hook and gets you updates through /plugin — no manual git pull.

Or manually as a bare skill:

git clone https://github.com/alifazl3/dokit.git
ln -s "$PWD/dokit/skills/dokit" ~/.claude/skills/dokit   # or .claude/skills/ per project

Then in any session: ask Claude to document something, or invoke /dokit. Claude scaffolds the tree, picks templates, enforces the Definition of Done, and keeps CHANGELOG.md current as part of finishing each change.

After updating the skill (via /plugin or git pull), run /dokit upgrade in each project: it re-checks the whole docs/ tree against the current version of the standard and fixes documents written under older versions — safe to run any time, it changes nothing on a conforming tree.

Use the scripts directly (no Claude needed)

python skills/dokit/scripts/init_docs.py /path/to/project            # full structure
python skills/dokit/scripts/init_docs.py /path/to/project --minimal  # small projects
python skills/dokit/scripts/validate_docs.py /path/to/project        # lint (exit 1 on errors)

What's inside

dokit/
├── .claude-plugin/
│   ├── plugin.json           # plugin manifest
│   └── marketplace.json      # the repo is its own marketplace
├── hooks/
│   └── hooks.json            # plugin installs auto-register the Stop hook
└── skills/dokit/
    ├── SKILL.md              # the skill: rules Claude applies + workflow
    ├── references/
    │   ├── standard-fa.md    # full DocOS standard (fa)
    │   └── structure.md      # folder map quick reference
    ├── templates/            # ADR, feature, entity, service, api, runbook,
    │                         # playbook, scenario, incident, release,
    │                         # architecture, changelog entry
    ├── hooks/
    │   └── changelog-stop-hook.sh  # Stop hook: no change ends without its
    │                               # docs/changelog/{date}_{title}.md entry
    └── scripts/
        ├── init_docs.py      # scaffold docs/ in a project
        └── validate_docs.py  # lint the docs/ tree (CI-friendly)

Per-change changelog entries are on by default: every finished change also writes docs/changelog/{date}_{title}.md (Summary, Files Changed, Tests Run, Follow-ups / Risks). Ask Claude to skip them if you don't want that, or leave the Stop hook unregistered — SKILL.md shows the one-block .claude/settings.json registration.

With special thanks to @shakouri10, who came up with the idea for this documentation system — after a few attempts together, it grew into this skill.

{
  "name": "dokit",
  "owner": {
    "name": "ali fazlollahi",
    "url": "https://github.com/alifazl3"
  },
  "metadata": {
    "description": "DocOS — a complete documentation standard for software projects, packaged as the dokit Claude Code plugin."
  },
  "plugins": [
    {
      "name": "dokit",
      "source": "./",
      "description": "DocOS — Documentation Operating System. A complete documentation standard for software projects: numbered docs/ taxonomy, a template for every document type, lifecycle rules, and a docs Definition of Done — with scaffold and lint scripts."
    }
  ]
}