docflow

docflow

docflow gives your AI coding assistant a memory. It creates a small set of Markdown files in your project — a place for what the product does, how it's built, why choices were made, and what shipped each month. Every time you start a session, your assistant reads the latest of these automatically, so it already knows the project instead of guessing. No database, no service to run — just text files and a few small Bash scripts.

Status: early MVP developer tool. This is not a document approval, e-signature, or workflow-analytics SaaS.

Words you'll see (one line each)

• ADR — a short note recording a decision and why you made it.
• Scaffold — create the starter folders and files for you, automatically.
• Spec — a description of how something works.
• Changelog — a monthly log of what shipped.

Full glossary: docs/references/glossary.md.

Start here

1. Install the plugin (see Claude Code below).
2. Open your project and type /docflow:doctor. It looks at your repo and tells you the one command to run next.
3. Run that command. Done.

You don't have to choose between setup paths yourself — doctor decides. (If you want to: init for an empty repo, adopt if docs already exist, repair to refresh an existing docflow setup.)

Two ways to use it

Every docflow capability works two ways — pick whichever feels natural:

• Type a command: /docflow:check, /docflow:doctor, /docflow:validate, …
• Just ask in plain English: "is docflow set up here?", "where's the spec for X?", "add this to the changelog" — the matching skill triggers automatically.

What It Does

• Creates a 7-folder documentation taxonomy for product behavior, implementation, decisions, references, plans, reviews, and changelog history.
• Audits existing repos before setup, then recommends init, adopt, or repair.
• Adds a monthly append-only changelog so agents and humans can see what shipped recently.
• Auto-loads the docs map and newest changelog into each session via a read-only SessionStart hook.
• Works in Claude Code (commands + skills + hook), Codex (manifest + skills), and any agent via the scaffolded AGENTS.md.
• Keeps everything as plain Markdown plus small Bash scripts.

Demo

Example scaffold output is committed under examples/basic-repo.

Minimal flow:

bash scripts/scaffold.sh --target /path/to/repo --docs-root docs --project "My App"
cd /path/to/repo
find docs -maxdepth 2 -type f | sort
CLAUDE_PROJECT_DIR="$PWD" bash /path/to/docflow/hooks/docflow-context.sh

Expected result:

• docs/README.md becomes the human-readable documentation index.
• docs/INDEX.md becomes the compact path-to-purpose map agents read first.
• docs/changelog/ holds monthly shipped-work memory.
• AGENTS.md tells Codex and other repo-aware agents where to start.

The 7 Categories

Folder	Answers	Naming
product-spec/	What a feature does for users	NN-topic.md
specs/	How it is built	(mmm-yy)-topic.md
decisions/	Why a choice was made	NNNN-title.md
references/	Rules, conventions, cheat sheets	topic.md
plans/	Roadmap and work status	(mmm-yy)-name.md, upcoming/*
reviews/	Quality, audits, known bugs	(mmm-yy)-topic.md, bugs/
changelog/	What shipped by month	(mmm-yy).md

Full naming rules ship in templates/NAMING.md.

Agent Setup

Use this section to install docflow for each agent. Replace /path/to/docflow with your local clone path, for example /Users/Adem/Desktop/migration/docflow.

Recommended setup flow in any repo:

1. Run doctor first.
2. If the repo has no docs, run init.
3. If the repo already has docs, run adopt.
4. If docflow already exists, run repair.

Claude Code

Claude Code has native plugin support.

Install from a local checkout inside Claude Code: