datax-doc-flow

Scaffolds documentation conventions and AI-assisted doc generation into any frontend repo.

What it sets up

Running the init command adds the following to your repo:

.conventions/      ← format rules for each doc (read by AI agents)
  RULES.md         ← global writing rules
  overview.md      ← (and others based on your selection)
AGENTS.md          ← entry point for AI agents
docs/              ← stub files for each selected doc
scripts/
  document.mjs     ← automation script
package.json       ← gets a new "document" script

Usage

Init (one-time per repo)

npx datax-doc-flow

This runs an interactive prompt where you pick which docs to activate, then scaffolds everything above into the current directory. Run from the repo root.

Generate docs

Once set up, generate all active docs:

npm run document

Update a single doc:

npm run document -- overview

Preview what will run without writing:

npm run document -- --dry-run

Requires the Claude CLI:

npm install -g @anthropic-ai/claude-code
claude login

Working with doc flags

The generated docs use three inline markers. Here is what each means and what to do when you encounter one.

TODO: <note>

Something could not be confirmed from the codebase when the doc was generated. The note tells you where to find the missing value.

What to do: look up the value, write it into the appropriate section, and delete the TODO: line. Never leave a TODO: without a note — if you cannot resolve it yet, keep the note so the next person knows where to look.

⚠️ Verify: <note>

A conflict was detected between the doc and the source code. The note describes what differs.

What to do: check the source code, resolve the conflict, update the doc with the correct value, and remove the flag. Do not ignore it — a stale ⚠️ Verify: signals to the next engineer that this section is unreliable.

Open questions section

Unresolved questions that require a human decision or team input. These are not gaps the agent can fill from the codebase alone.

What to do:

• If the question is now answered — write the answer into the appropriate section and delete the question.
• If it needs a team decision — link a GitHub issue, e.g. [#123](https://github.com/org/repo/issues/123). The agent will preserve the link on future runs.
• If the question was never meant to be answered (deliberate omission) — replace it with a note explaining the intent, e.g. "Not applicable — backend team owns this." The agent will stop raising it.
• If the agent flags something as missing that was never intended to be there — add a short inline note in the relevant section, e.g. "Out of scope by design." The agent will preserve it and stop flagging it.

Publishing (maintainers)

First-time setup

npm login
# Enter your npmjs.com credentials when prompted

Publish

npm publish --access public

Update and republish

Bump the version in package.json first:

npm version patch   # 1.0.0 → 1.0.1  (bug fixes)
npm version minor   # 1.0.0 → 1.1.0  (new docs / features)
npm version major   # 1.0.0 → 2.0.0  (breaking changes)

npm publish --access public

Updating an existing repo

When conventions are updated and a new version is published, re-run the init command in the target repo:

npx datax-doc-flow@latest

It will overwrite .conventions/ files and scripts/document.mjs but skip existing docs/ files so your content is not lost.