INSERT REPOSITORY. GENERATE DOCUMENTATION. NO INVENTED LORE.
An Agent Skill that designs, writes, audits, and maintains documentation grounded in the actual source.
Created by Jonas Kahn, Docforge is a source-grounded documentation cartridge for AI coding agents. It ships as an Agent Skill and a Claude Code plugin: instructions, references, templates, schemas, and paired Python/Node tools—not a Markdown generator library.
- Boot sequence
- Start game
- Core loop
- Graph cartridges
- Stage select
- Controller mapping
- Inventory
- System requirements
Prerequisites for the Agent Skills install path:
- a compatible coding agent
- Node.js 18+ with
npm/npx git- network access
# Install in the current project
npx skills add jonaskahn/docforge
# Install globally for supported agents
npx skills add jonaskahn/docforge -g -yPackage metadata declares support for Claude Code, Codex, OpenCode, and Gemini CLI. The commands above come from meta.json; they require external network access and were not executed during this README update.
Docforge also ships a native Claude Code marketplace manifest:
/plugin marketplace add jonaskahn/docforge
/plugin install docforge@docforge
Both install paths load the same SKILL.md. These package-declared plugin commands were not executed during this README update.
Describe the documentation quest in plain language:
Document this repository from scratch.
Create diligence documentation for this service.
Generate ADRs from the repository history.
Add the API-service shape and Business Analyst audience.
Make this repository ready for AI coding agents.
Check which generated docs have drifted from source.
Slash-command support depends on the host. Where registered, use /docforge; plain-language requests work across compatible agents.
/docforge
Expected result:
- Docforge performs only read-only discovery: repository/manifest state and available graph sources.
- It presents all applicable unresolved scope questions together: goal, documentation tier, the five typed repository-profile dimensions, graph source only when it is unresolved, and execution mode. Each question explains its choices; native selection controls are used when the host provides them.
- After you answer the set, it summarizes the complete scope and asks you to confirm, edit, or cancel. This confirmation is required even when Auto-accept is selected. It does not create a manifest, documents, or a graph index during intake.
- After you confirm the scope, it reuses the selected provider’s persisted graph and native skill/MCP queries to inventory the repository.
- It always shows the exact manifest-backed tree plus a one-line content/evidence card for every document before writing. Auto-accept skips only the pause, not the displayed tree.
- If discovery changes the manifest later, it shows the path/requirement delta and refreshed tree before writing continues.
If no code graph exists, Docforge explains the setup choices. It never installs or wires a provider automatically, and it requests separate approval before an agent runs a repository index build or refresh.
PRECHECK → ANALYZE → PLAN → WRITE → AUDIT → TRACK
- PRECHECK — require one supported code graph.
- ANALYZE — read graph data, source, config, manifests, existing docs, CI, deployment files, git history, and child repositories.
- PLAN — choose a named tier and typed profiles, harvest a complete ranked flow index, initialize manifest 3.1, then preview its exact tree.
- WRITE — generate one document at a time in dependency order.
- AUDIT — use a fresh artifact-only reviewer when supported, otherwise a recorded cold artifact-only pass; derivable gaps force a rewrite.
- TRACK — stamp section-level source paths and git blob hashes so later runs update only what drifted.
Docforge writes behavior and boundaries, not prose tied to private symbols or line numbers. Derivable facts must be completed; only truly external values may remain as typed tokens such as <SECURITY_CONTACT>.
Read the full workflow, document contracts, audit gate, and provenance model.
A code graph is the universal key. Docforge reuses, rather than replaces, the provider’s pre-generated index:
- Understand Anything’s shareable code-graph and flow-graph JSON, queried through its skills or the deterministic JSON reader;
- GitNexus’s LadybugDB code graph and indexed processes, queried through its MCP/skills or project-local CLI;
- CodeGraph’s auto-synchronized SQLite index, queried through
codegraph_explorefor relevant source, call paths, and blast radius.
Only one readable provider is required. When GitNexus, Understand Anything, or CodeGraph is ready, the normal intake reports and uses that provider; absent competitor indexes are not gaps and stay hidden unless you request provider comparison or troubleshooting.
Docforge writes every evidenced flow candidate to .docforge/flow-index.json
and renders the full matrix in docs/flows/README.md. Harvest ranks candidates
as main/deferred; revise flow upserts them as placeholder with stub files and
fully documents main-priority flows (with an explicit user notice). GitNexus
Processes are grouped by entry point, while Understand Anything domain flows
are augmented from its knowledge graph. Only catalog entries declaring
flow_graph require detailed flow data. They prefer native flow data; when
only a code graph is available, Docforge derives a provisional,
entry-point-first flow graph in the git-ignored .docforge/tmp/ workspace.
Provider capabilities and setup live in graph dispatch; the reasoning loop lives in flow derivation.
Choose Spine for a repository baseline, Diligence for external scrutiny, or Portfolio for a multi-repository review. Docforge then composes five independent profile dimensions:
- shapes such as
web-app,api-service,mobile-app,desktop-app,cli-tui,library-sdk,data-pipeline,infrastructure-platform,game,embedded-iot, andsmart-contract; - platforms such as
browser,ios,android,macos,windows,linux, wearable/TV/spatial targets, cloud, containers, edge, and RTOS; - framework detection profiles such as Flutter, React Native, KMP, MAUI, Electron, Tauri, SwiftUI/AppKit, popular web/backend/data frameworks, game engines, and embedded toolchains;
- evidenced concerns such as accessibility, localization, privacy, secure storage, offline sync, payments, notifications, and hardware integration;
- audiences such as engineers, beginners, Business Analysts, Product Owners, coding agents, operators, and security reviewers.
Frameworks tailor detection, graph queries, terminology, and verified commands;
shapes and platforms own the durable document tree. Shared paths are selected
once and retain every profile origin. With no audience flag, manifest
initialization records engineers and beginners as the default audience.
The Business Analyst audience generates a business process view, rule catalog,
and requirements traceability. The Product Owner audience generates feature
value/status, success metrics, release impact, and ticket traceability only
when ticket evidence exists. Select coding-agents (aliases include agent
and agent-context) for a compact AGENTS.md kernel, Claude shims/settings,
and token-budgeted docs/agents/ views.
The tier rules, profile signals, and complete level layout live in the canonical docs tree and SKILL.md.
Use --revise all or --revise <area> for stale content, --plan-only to stop after manifest initialization and preview, --resume to continue a saved run, and --status for a read-only progress report.
--auto-accept skips routine conversational pauses after the scope has been
explicitly confirmed. It does not silently choose unresolved profiles or
authorize installation, global configuration, graph construction or refresh,
archive/delete actions, or other separately approved side effects; it also
does not skip grounding, plan display, audits, or final checks.
The exact flag semantics and composition rules live in the workflow.
SKILL.md is the entry cartridge. .metadata/catalog.json is the canonical registry; references/ holds owned prose contracts, instructions/ holds writing craft, and assets/templates/ holds output scaffolds.
scripts/ contains paired Python and Node tools for
profile detection, graph adapters, flow derivation, scaffolding, linting,
manifest state, staleness checks, and child-repository discovery.
.claude-plugin/ and meta.json package the
same skill for its two distribution paths.
- a compatible AI coding agent
git- one supported code-graph producer
- Python 3.10+ or Node.js 18+ for the bundled tools
Core tools use only the selected runtime's standard library or built-ins. The optional offline GitNexus reader is the exception: it needs @ladybugdb/core or a compatible LadybugDB Python binding. GitNexus MCP tools are preferred.
Found a bug or missing rule? Open an issue with the request, actual output, and expected output.
To contribute, edit the relevant workflow, reference, template, schema, and Python/Node pair together, then open a pull request. New graph providers follow the graph-source extension contract.
SPDX-License-Identifier: MIT — LICENSE