docforge

Generate client-facing feature briefs (.docx) from a PRD + SPEC pair using Claude.

docforge reads a folder containing your product requirements (PRD.md) and technical spec (SPEC.md), interviews you with 3–5 short questions, calls the Anthropic API with a saved "feature brief writer" prompt, and emits a styled Word document ready to share with non-technical clients, portfolio readers, or stakeholders.

Installation

gem install docforge

Requires Ruby 3.2+ and an Anthropic API key.

Quickstart

# 1. Set your API key
export ANTHROPIC_API_KEY=sk-ant-...

# 2. Lay out a feature folder
mkdir -p ~/Desktop/MyFeature
cp /path/to/PRD.md  ~/Desktop/MyFeature/
cp /path/to/SPEC.md ~/Desktop/MyFeature/

# 3. Generate the brief
docforge generate ~/Desktop/MyFeature

The first run interviews you, calls the API, caches the response next to the inputs, and writes a .docx to ~/Desktop/Portfolio/Features/ (or wherever you've configured).

Re-runs read from the cache instantly — no further API spend until you pass --fresh.

Per-project configuration

docforge reads layered config with this precedence (highest first):

1. Env vars — ANTHROPIC_API_KEY, ANTHROPIC_MODEL, DOCFORGE_OUTPUT_DIR, DOCFORGE_AUTHOR
2. Project config — ./.docforge.yml (or --config PATH)
3. Global config — ~/.docforge.yml
4. Built-in defaults

Generate a starter config:

docforge init

Example .docforge.yml:

model: claude-sonnet-4-5
output_dir: ~/Desktop/Portfolio/Features
author: Your Name

# Some projects use different filenames
input_files:
  prd: requirements.md
  spec: design.md
  notes: thoughts.md

# Custom prompt for this domain (relative to this yaml)
system_prompt: ./prompts/feature_brief.md

# Replace the default 5 interview questions
interview:
  - "Who is the human user of this feature?"
  - "What broke before this shipped?"
  - "What's the hardest tradeoff you made?"

Commands

docforge init                            # write a starter .docforge.yml
docforge config                          # show resolved config + loaded files
docforge generate FOLDER                 # generate brief from a feature folder
docforge generate FOLDER --fresh         # ignore cache, re-call API
docforge generate FOLDER --dry-run       # show what would happen; no API call
docforge generate FOLDER --no-interview  # skip the interview
docforge -c path/to/config.yml generate FOLDER  # explicit config path

Caching

After a successful API call, docforge writes .brief-cache.json next to your PRD/SPEC. Subsequent renders read from cache — useful for iterating on styling without burning tokens. Delete the file or pass --fresh to re-call.

Folder layout

<feature_folder>/
  PRD.md                # required (name configurable)
  SPEC.md               # required (name configurable)
  notes.md              # optional — your "what I'm proud of" notes
  _assets/              # optional — screenshots, diagrams
    01-overview.png
    02-flow.png
  .brief-cache.json     # auto-generated, contains the model response

Environment variables

Variable	Purpose	Default
ANTHROPIC_API_KEY	Required. Anthropic API key.	—
ANTHROPIC_MODEL	Model id.	claude-sonnet-4-5
DOCFORGE_OUTPUT_DIR	Where the .docx lands.	~/Desktop/Portfolio/Features
DOCFORGE_AUTHOR	Byline used in the brief.	You

License

MIT — see LICENSE.