DocFlow 🚀

Agent-Powered, LLM-Optimized Documentation Generation & MCP Serving System

DocFlow automatically generates, updates, and serves dual-audience documentation (rich Markdown for humans + high-density JSON for LLMs) from Git repository activity.

Unlike traditional doc tools that rely on direct LLM API keys or lock you into specific vendors, DocFlow generates minimal, focused "caveman prompts" that can be executed by any coding agent (Antigravity, Cursor, Claude Code, Cline, Codex, Hermes, Continue, etc.) within your organization's approved toolset.

---

🔑 Key Features

• 🔗 1 App Repo : 1 Doc Repo Model: Strict 1-to-1 pairing between an application source repository (or monorepo root) and its dedicated documentation repository.
• 🏗️ Infrastructure First: Automatically scans and documents system architecture, frameworks, and hosting environments (Dev/Staging/Prod) before chunking feature modules.
• 🤖 Agent Agnostic: Zero LLM API key dependencies. Generates structured task prompts in prompts/pending/ for any agent to execute.
• 📄 Dual-Audience Output: Maintains human-readable index.md and token-optimized context.json for every feature module.
• 🌐 MCP Server Included: Built-in FastMCP server serving documentation tools (search_docs, get_feature, get_wip, get_full_context) over stdio and sse.
• 📁 Decoupled Doc Repo: Keeps documentation in a separate, dedicated repository to keep application source repositories clean.
• 📌 Work-In-Progress Tracking: Scans active feature branches and updates status/wip.md & status/wip.json.
• 🌐 Standard Specification Support: Automatically generates llms.txt and llms-full.txt discovery files.
• 🐙 Multi-Platform MR/PR Creation: Automated branch creation, committing, pushing, and Pull/Merge Request opening for GitHub, GitLab, and Bitbucket.

---

📐 Architecture & Workflow

App Repo (Merge/Release) ──→ DocFlow Git Analyzer
                                    │
                                    ▼
                          Prompt Builder (Jinja2)
                                    │
                         Caveman Task Prompt
                                    │
                                    ▼
                           Agent Runner (shell / manual)
                                    │
                                    ▼
                         Target Docs Repository
                          ├── architecture/ (Hosting & Frameworks) [Init First]
                          ├── features/<feature>/
                          │     ├── index.md (Human)
                          │     └── context.json (LLM)
                          ├── status/ (wip.md, wip.json)
                          ├── prompts/ (pending/ & completed/)
                          ├── llms.txt & llms-full.txt
                          └── CONVENTIONS.md
                                    │
                                    ▼
                         Doc Branch & MR Creator
                                    │
                                    ▼
                           FastMCP Server
                          (stdio / SSE transports)

---

⚡ Quick Start

Installation

# Clone the repository
git clone https://github.com/YOUR_USERNAME/docflow2.git
cd docflow2

# Create a virtual environment (recommended for Linux/PEP 668)
python3 -m venv --without-pip .venv
curl -sS https://bootstrap.pypa.io/get-pip.py | .venv/bin/python3

# Install DocFlow in editable mode
.venv/bin/pip install -e .

# Activate the virtual environment
source .venv/bin/activate

Basic Commands

# 1. Initialize documentation for an application repository
docflow init --repo /path/to/app-repo --docs /path/to/docs-repo --mode manual

# 2. Track active feature branches & work-in-progress
docflow status --repo /path/to/app-repo --docs /path/to/docs-repo

# 3. Generate documentation update prompts from git diffs
docflow generate --repo /path/to/app-repo --docs /path/to/docs-repo --from main~1 --to main

# 4. Commit doc updates, push branch, and create Pull Request
docflow publish --docs /path/to/docs-repo --platform github

# 5. Start the MCP Server for LLM agent integration
docflow serve --docs /path/to/docs-repo --mode stdio

---

📂 Documentation Repository Layout

docs-repo/
├── CONVENTIONS.md                        # Documentation format standards
├── llms.txt                              # Discovery index
├── llms-full.txt                         # Concatenated context file
│
├── architecture/                         # Baseline architecture & infrastructure
│   ├── index.md                          # Frameworks, Dev/Staging/Prod envs
│   └── context.json                      # Compact LLM metadata
│
├── features/                             # Feature-based documentation
│   ├── authentication/
│   │   ├── index.md                      # Detailed human docs
│   │   ├── context.json                  # Compact LLM JSON
│   │   ├── files.md                      # File manifest
│   │   └── changelog.md                  # Historical change log
│   └── ...
│
├── status/                               # Work-in-progress active branch docs
│   ├── wip.md
│   └── wip.json
│
└── prompts/                              # Task prompt repository
    ├── pending/                          # Prompts waiting for agent execution
    └── completed/                        # Completed task prompts (audit log)

---

⚙️ Configuration (.docflow.yml)

Place .docflow.yml in your application repository root or documentation repository root:

project:
  name: "MyApplication"

app:
  repo_path: "/path/to/app-repo"

docs:
  repo_path: "/path/to/docs-repo"

agent:
  mode: "shell"                          # "shell" (automatic CLI agent execution) or "manual" (stage prompts in prompts/pending/)
  command: "agy --dangerously-skip-permissions --add-dir {docs_repo} -p \"$(cat {prompt_file})\""

platform:
  type: "github"                         # github | gitlab | bitbucket | generic
  auto_mr: true

generation:
  full_diff_threshold: 200
  ignore:
    - "*.lock"
    - "node_modules/"
    - "dist/"
    - "__pycache__/"

Agent Execution Modes

• Shell Mode (mode: shell): DocFlow invokes your CLI coding agent (e.g., agy, opencode, claude) to execute task prompts immediately. The agent writes files directly into target paths in your documentation repository, and DocFlow moves executed prompts from prompts/pending/ to prompts/completed/.
• Manual Mode (mode: manual): DocFlow generates prompts inside prompts/pending/. Each prompt includes an explicit CRITICAL OUTPUT FILE LOCATION DIRECTIVE with exact target absolute paths so that external agents write files directly into the target docs repository.

---

📊 Configuration Dashboard (docflow info)

View repository pairing, agent settings, documented feature modules, and pending task prompts at any time:

docflow info

Output:

DocFlow Information Dashboard
  Project Name: MyApplication
  App Repo:     /path/to/app-repo (exists)
  Docs Repo:    /path/to/docs-repo (exists)
  Agent Mode:   shell (agy --dangerously-skip-permissions --add-dir {docs_repo} -p "$(cat {prompt_file})")
  Platform:     github
  Documented Features (7): config, core, components, scripts, public, pages, lib
  Pending Prompts (0): None

---

🧪 Testing

Run the full pytest suite:

pytest -v

---

📜 License

This project is licensed under the MIT License.