docflow

Why DocFlow · Install · Demo · Context proof · Example repo · Security

DocFlow gives AI coding agents durable project memory. It organizes what the product does, how it works, why decisions were made, what is planned, and what shipped—then routes the agent to the smallest relevant document.

Plain Markdown. Small Bash helpers. No database, hosted service, or source-code rewrite.

Status: early MVP. Claude Code plugin setup works today. Codex works through repository guidance and local plugin development; a public Codex directory listing is not published yet.

Why DocFlow

What changes in your repository

your-repo/
├── AGENTS.md                 # agent start and routing rules
├── GEMINI.md                 # points Gemini to the same rules
├── .cursorrules              # points Cursor to the same rules
├── docflow.json              # docs root + validation profile
├── docs/
│   ├── README.md             # human documentation hub
│   ├── INDEX.md              # compact map agents read first
│   ├── product-spec/         # WHAT the product does
│   ├── specs/                # HOW it is implemented
│   ├── decisions/            # WHY choices were made
│   ├── plans/                # planned and in-progress work
│   ├── reviews/              # audits, quality, and known bugs
│   └── changelog/            # shipped outcomes by month
└── scripts/                  # doctor, repair, map, links, validation

DocFlow does not move existing documentation during adoption, edit application source code, call a remote service, or silently fix user-authored content.

Install And Run

Claude Code — plugin setup

Run these inside Claude Code:

/plugin marketplace add https://github.com/MedAdemBHA/docflow
/plugin install docflow
/reload-plugins

Then open the target repository:

/docflow:doctor

Run the one next command it recommends. Type /docflow: to browse commands, or ask naturally: “is DocFlow ready here?”, “where is authentication documented?”, or “add this release to the changelog.”

Codex, Gemini, Cursor, or any agent — repository setup

This is the verified portable path today:

git clone https://github.com/MedAdemBHA/docflow.git
cd docflow

# Read-only diagnosis first
bash scripts/docflow-doctor.sh --target /path/to/your-repo

# Empty/new documentation
bash scripts/scaffold.sh --target /path/to/your-repo --docs-root docs --project "My App"

# OR: preserve and adopt existing documentation
bash scripts/docflow-adopt.sh --target /path/to/your-repo --docs-root docs --project "My App"

Open the target repository in your agent. Codex reads AGENTS.md; Gemini and Cursor are pointed to the same rules. Confirm readiness with:

bash /path/to/docflow/scripts/docflow-check.sh --target /path/to/your-repo

Codex plugin status

The repository includes a valid .codex-plugin/plugin.json, but DocFlow is not yet published in the public plugin directory. For local plugin development, add the source through a personal/local marketplace, install it from the Codex /plugins browser, and start a new session. See the official OpenAI plugin workflow.

Until the public listing ships, use the repository setup above instead of copying an unverified codex plugin add command.

First command: doctor

Core commands

Full command and skill reference: docs/references/commands.md.

Token And Context Efficiency

DocFlow does not compress the content of project documentation. It reduces context use by loading a small routing layer first, then opening full documents only when the task requires them.

The default Claude SessionStart payload contains:

1. Up to 30 non-empty lines from docs/INDEX.md (path → purpose).
2. Up to 20 non-empty lines from the newest real monthly changelog.
3. Within that changelog budget, the document header, Summary, and newest detailed entry—not the full month.

The agent then opens the exact product spec, technical spec, ADR, plan, review, or reference needed for the current task. AGENTS.md uses the same route-first workflow for Codex, Gemini, Cursor, and other repo-aware agents, although automatic SessionStart injection is Claude-specific.

Measured on two established repositories

Measurements taken on 2026-08-13 with wc -w, using the default hook limits:

These are word counts, not tokenizer-specific token counts. Actual tokens depend on the model tokenizer, Markdown, code, and file paths. The comparison is still useful because it measures the exact text boundary DocFlow controls: full documentation versus the bounded automatic payload.

What the saving does—and does not—mean

• The hook avoids injecting the full documentation corpus at session start.
• docs/README.md and task-specific documents may be read afterward, so total task context will be higher than the hook payload.
• A broad audit can legitimately open many documents; DocFlow optimizes ordinary targeted work, not tasks that require the whole corpus.
• Savings depend on agents following INDEX.md and AGENTS.md instead of scanning every documentation file.
• Limits can be tuned with DOCFLOW_INDEX_LINES and DOCFLOW_LOG_LINES; smaller values save more context but expose less navigation/history.

Reproduce the measurement:

repo=/path/to/repo
find "$repo/docs" -type f -name '*.md' -print0 | xargs -0 wc -w | tail -n 1
CLAUDE_PROJECT_DIR="$repo" bash /path/to/docflow/hooks/docflow-context.sh | wc -w

See Context efficiency for the measurement contract, formula, and interpretation rules.

Live Demo

The committed example repository is a complete, validation-clean DocFlow setup—not a screenshot or pseudocode.

# From the DocFlow repository root
bash examples/basic-repo/scripts/docflow-check.sh --target examples/basic-repo
CLAUDE_PROJECT_DIR="$PWD/examples/basic-repo" bash hooks/docflow-context.sh

Readiness output:

DocFlow Check
- status: Ready
- docs root: docs (yes)
- validation: profile=strict errors=0 warnings=0
- next: No action needed.

Follow one feature across the documentation lifecycle:

Browse the human docs hub, agent route map, or agent instructions.

Documentation Model

Full naming rules: templates/NAMING.md.

Validation Profiles

Both profiles block broken local links, stale generated indexes, and Markdown documents without an H1. Adoption preserves existing folders and section vocabulary.

Trust And Safety

docflow asks users to install an AI-agent plugin and run Bash. That deserves explicit proof.

• Read SECURITY.md before installing.
• CI runs shellcheck on scripts and hooks.
• CI runs scripts/test-scaffold.sh, covering idempotency, special-character project names, JSON validity, link checks, and hook behavior.
• The Claude SessionStart hook is read-only and prints truncated docs context only.

Run checks locally:

bash scripts/test-scaffold.sh
for t in tests/*.sh; do bash "$t"; done
shellcheck scripts/*.sh hooks/*.sh tests/*.sh

Repository Layout

docflow/
├── .claude-plugin/          # Claude plugin manifest
├── .codex-plugin/           # Codex plugin manifest
├── .github/workflows/       # CI
├── commands/                # Claude slash commands
├── examples/basic-repo/     # Filled example output
├── hooks/                   # SessionStart context hook
├── repo-templates/          # AGENTS.md, GEMINI.md, .cursorrules
├── scripts/                 # doctor, adopt, repair, scaffold, map, generators, tests
├── skills/                  # doctor/check/init/adopt/repair/validate/router/author/changelog
└── templates/               # generic docs skeletons

Agent Support

The portable product is the docs tree and workflow. The plugin runtime is agent-specific.

Typical Workflow

1. Run doctor to inspect the repo.
2. Run init for empty docs, adopt for existing docs, or repair for existing docflow.
3. Fill docs/README.md and product-spec/00-overview.md.
4. Write ADRs, specs, plans, and reviews using the category templates.
5. Append shipped work to the current monthly changelog.
6. Run repair after adding or renaming docs, or when managed helpers have an update.

Share DocFlow

Choose the clean 1200×630 context card, detailed context explainer, or feature overview, then copy a tailored caption for X, LinkedIn, Reddit, or Quora.

Contributing

See CONTRIBUTING.md.

Documentation

This repo dogfoods its own docs system. Browse the knowledge base at docs/README.md — start with docs/INDEX.md for the full path → purpose map.

Changelog

See CHANGELOG.md.

Star History

License

MIT - see LICENSE.