KingmaDoc

Feature docs for AI coding agents, before and after the code. When an agent builds a feature, it's easy to end up with code nobody fully understands: code blindness. KingmaDoc fixes that with two documents per feature. Before implementation, plan analyzes your codebase, asks up to five clarifying questions and writes a plan doc with scope, assumptions, risks, open questions and C4 architecture diagrams. After implementation, verify compares the code with that plan and lists the deviations and validation results. Use it as a Python CLI, or with no install at all as a Markdown skill for Claude Code, Cursor, Codex or GitHub Copilot.

Status: 0.2.0. plan is complete. kingmadoc --version shows the version and the installed commit. verify compares the code with the plan (changed files, expected files, requirements, containers) and runs the project's checks with --run-checks. See CHANGELOG.md.

Installation

pipx (recommended for the CLI)

Requires Python 3.11+.

pipx install kingmadoc      # from PyPI
pipx upgrade kingmadoc      # later: update to the newest release

Beta: every commit on main that passes CI is published as a development version (e.g. 0.3.0.dev12). Plain installs ignore it; to follow the beta:

pipx install --pip-args=--pre kingmadoc   # once (pipx remembers --pre)
pipx upgrade kingmadoc                    # later: the newest beta

For the latest commit instead of a release, install from GitHub with pipx install git+https://github.com/ATkingma/KingmaDoc and update it with pipx reinstall kingmadoc; kingmadoc --version then shows the commit (0.2.1.dev3 (git 1a2b3c4)). (pipx install --force fails on recent pipx versions with "Failed to create virtual environment" and keeps the old version.) An install from before 0.2.0 came from GitHub: pipx uninstall kingmadoc && pipx install kingmadoc switches it to the releases.

Then, in your project, install the agent skills; that's all:

kingmadoc skills install                    # Claude Code (.claude/skills/)
kingmadoc skills install --agent cursor     # or: codex, copilot

Run it again after updating KingmaDoc: skill files still as an earlier version installed them are updated; files you edited are kept (--force replaces them too).

Nothing else to install: the first kingmadoc render downloads the D2 diagram renderer by itself (pinned version, checksum-verified; KINGMADOC_D2_DOWNLOAD=0 turns that off). The pictures are PNG files linked from plain Markdown, so every Markdown preview shows them: Visual Studio and Rider (preview on by default), VS Code (Ctrl+Shift+V), GitHub, GitLab and Bitbucket. render --format svg links the SVG instead, which follows dark mode. VS Code opens .md as text: kingmadoc skills install offers to make it open explainers as a preview (--vscode-user for every folder, --vscode for this project).

pip

pip install kingmadoc   # into the current environment

Markdown-only (no Python)

Without the CLI, copy the skill files into your project; the agent follows them and writes the same docs itself (diagrams then stay as text unless d2 is installed).

mkdir -p .claude/skills/kingmadoc && cp skill/SKILL.md .claude/skills/kingmadoc/SKILL.md
mkdir -p .cursor/rules && cp skill/cursor.md .cursor/rules/kingmadoc.mdc
cat skill/codex.md >> AGENTS.md
mkdir -p .github && cat skill/copilot.md >> .github/copilot-instructions.md

Then ask the agent to "plan " or "verify ". If the kingmadoc CLI is installed, the skill uses it for the codebase analysis.

Explaining existing code. A second skill, skill/explaining-code/SKILL.md, explains code that already exists, with pictures: a feature, a branch (what did this branch or task change), a whole project, or a part of one. Each subject gets its own folder with a unique ID, docs/explain/<NNNN>-<name>/ (the explainer README.md plus its img/), listed in docs/explain/README.md; explaining it again updates that folder. The explainer is one document, or on request (or with explain: {documents: split}) a functional and a technical document next to a cover page (FO/TO: user stories with use cases, screenshots and evil user stories; a threat model in the technical side). It is by default an arc42 architecture document (the twelve arc42 sections, with C4 diagrams per level, runtime flows and deployment), or a compact C4 zoom-in with explain: {format: c4} in .featuredoc.yml. Every figure is numbered, rendered as an image and decoded by a small table. The C4 diagrams follow Simon Brown's notation (title, legend, element type and technology, labelled one-way arrows); the agent adds the models the code calls for (UML sequence, state machine, class, activity with swimlanes, use case, ER, data flow with trust boundaries, context map), each drawn by its own notation rules. No stories, no audit. Install it next to the first one and ask the agent to "explain <feature / branch / project>". kingmadoc skills install installs it together with the first skill; the pictures are rendered with kingmadoc render as PNG, which every editor shows.

• The Codex and Copilot files are loaded in every session (about 17 KB). Codex stops reading AGENTS.md files after 32 KiB in total by default (project_doc_max_bytes). Lighter alternative: all three agents also support the Agent Skills standard, which loads a skill only when a request needs it. Copy the unmodified skill/SKILL.md to .cursor/skills/kingmadoc/, .agents/skills/kingmadoc/ (Codex) or .github/skills/kingmadoc/ (Copilot) instead.
• The Claude Code skill's allowed-tools includes Bash, so it can run git and your tests in verify mode without asking. Narrow it if you prefer to approve each command.
• The variants are generated from skill/SKILL.md (python3 scripts/build_skill_variants.py); don't edit them by hand.

Quick start

cd your-project
kingmadoc init                      # optional: writes .featuredoc.yml with all defaults
kingmadoc plan "Add password reset via email. Links expire after 30 minutes."
#   answer up to 5 questions (Enter skips; unanswered ones become open questions)
#   → docs/features/add-password-reset-via-email-plan.md
# review the plan, fill in the TODOs, approve it, then let your agent implement it
kingmadoc approve add-password-reset-via-email
kingmadoc verify add-password-reset-via-email [--run-checks]
#   → docs/features/add-password-reset-via-email-verify.md: deviations and check results;
#     the plan's status becomes implemented or partial
kingmadoc analyze --json            # just the codebase analysis, as JSON

The plan doc has: one-sentence summary, scope (in/out), assumptions, risks, C4 Context and C4 Container diagrams, open questions, and an appendix with the detected stack, entry points and file tree. See examples/verify-mode-plan.md for a real one, generated on this repository.

More commands:

kingmadoc plan "…" --no-input --stdout   # no questions, print instead of writing
kingmadoc plan "…" --models user_stories,screen_designs,threat_model   # only these models
kingmadoc threats threat-model.yml       # Microsoft Threat Modeling Tool threats for a DFD
kingmadoc explain scaffold "Checkout" --documents split   # empty FO + TO to fill in
kingmadoc explain check docs/explain/0001-checkout        # fails until every picture shows
kingmadoc screenshots http://localhost:8000 /cart=screen-us-1 -o docs/explain/0001-checkout/img
kingmadoc check add-login                # validate a plan's frontmatter and REQ IDs
kingmadoc approve add-login              # draft -> approved: the gate before code
kingmadoc explain new "Checkout"         # folder for a subject: docs/explain/0001-checkout/
kingmadoc render docs/explain/0001-checkout/README.md   # D2 diagrams -> SVG images
kingmadoc explain status [--check]      # which explainers the code changed under
kingmadoc explain facts --base main      # facts to explain from: data model, branch diff
kingmadoc adr "Use PostgreSQL" --status accepted   # needs adr.enabled

Configuration

All settings live in .featuredoc.yml in the project root; every key is optional and unknown keys are rejected, so typos don't go unnoticed. kingmadoc init writes the file with all defaults and comments; this repository's .featuredoc.yml is exactly that output.

Threat models

Threat models follow the Microsoft Threat Modeling Tool: its data flow notation, and its report (per interaction the threats, with state, priority and justification). The threats themselves come from Microsoft's own knowledge base, the tool's default template SDL TM Knowledge Base (Core), bundled from microsoft/threat-modeling-templates (MIT license, Copyright (c) Microsoft Corporation); kingmadoc threats evaluates its generation rules for every data flow the way the tool does.

Comparison

How KingmaDoc relates to tools with overlapping goals, based on each project's own documentation (September 2026). "Not documented" means we found no mention, not that the feature is absent.

They combine well: for example, plan with KingmaDoc, and use ProofShot as the UI evidence in the verification doc.

Contributing

Contributions are welcome. CONTRIBUTING.md covers the dev setup, running the tests, and adding a diagram backend or a template. Coding and documentation rules are in docs/conventions.md; all docs are indexed in docs/index.md. Please open an issue before large changes.

License

KingmaDoc is released under the MIT License; see LICENSE.