docforge 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e3c353d3c8c6d3270907b4cda066be13c12f8dc20ee5428ccb9a9705a817149a
+  data.tar.gz: 2ca10538751acb9e9a6ae7789e0a60b06352e190add675ddcd4028f736b3ca6f
+SHA512:
+  metadata.gz: 4a884fd16024bae5ebc2d7533dab5244f9512cbd5d9bf12fa57500fc668f6b0c4285daaac12bd63aaa4b0176cffa8613d4bf4ed7eba16278df783abd6717ac8e
+  data.tar.gz: 00ef52d132f593473526bb029eff9eef4ef0ba252980239f89c4eda2c121b2311e22df0a08a49a0e98a4852b7444780fdce325f0c511fb87844918dcd8e63427

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this gem will be documented in this file.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-15
+
+### Added
+- First public release.
+- `docforge generate FOLDER` — reads `PRD.md` + `SPEC.md` from a feature folder, runs them through Claude with a structured feature-brief prompt, renders a styled `.docx`.
+- `docforge init` — drops a starter `.docforge.yml` in the current directory.
+- `docforge config` — prints the resolved configuration and which config files were loaded.
+- Layered config: env vars > `./.docforge.yml` (or `--config PATH`) > `~/.docforge.yml` > built-in defaults.
+- Configurable input filenames, system prompt, interview questions, output directory, author, and model.
+- Tool-use forcing on the Anthropic Messages API to guarantee structurally valid JSON responses.
+- Per-feature response cache (`.brief-cache.json`) so re-renders don't re-spend tokens. Pass `--fresh` to bypass.
+- `--dry-run` flag to preview the prompt and skip the API call.
+- `--no-interview` flag to skip the interactive interview.
+- Spinner during API calls; raw response dumped to `/tmp/docforge-last-response.json` on every call for recovery.
+- Caracal-based `.docx` renderer with a "modern tech" visual style: Calibri, blue accent, table-heavy layout, callout for the pull quote.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rao Usama Abid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,112 @@
+# 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
+
+```bash
+gem install docforge
+```
+
+Requires Ruby 3.2+ and an Anthropic API key.
+
+## Quickstart
+
+```bash
+# 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:
+
+```bash
+docforge init
+```
+
+Example `.docforge.yml`:
+
+```yaml
+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
+
+```bash
+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](LICENSE).

data/bin/docforge

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "docforge"
+require "docforge/cli"
+
+Docforge::CLI.start(ARGV)

data/docforge.gemspec

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "lib/docforge/version"
+
+Gem::Specification.new do |spec|
+  spec.name        = "docforge"
+  spec.version     = Docforge::VERSION
+  spec.authors     = ["Rao Usama Abid"]                       # TODO before publish
+  spec.email       = ["usamaroar786@gmail.com"]          # TODO before publish
+  spec.summary     = "Generate client-facing feature briefs (.docx) from a PRD + SPEC pair using Claude."
+  spec.description = <<~DESC
+    docforge reads a feature folder containing a PRD and a SPEC, calls
+    the Anthropic API with a saved feature-brief writer prompt, and emits
+    a styled .docx ready to share with non-technical readers (clients,
+    portfolios, internal stakeholders).
+
+    Configurable per-project via .docforge.yml: input filenames, system
+    prompt, interview questions, output directory, and model.
+  DESC
+  spec.license = "MIT"
+
+  spec.required_ruby_version = ">= 3.2.0"
+
+  gh_user = "RaoUsamaAbid" # TODO before publish
+  spec.homepage             = "https://github.com/#{gh_user}/docforge"
+  spec.metadata["homepage_uri"]      = spec.homepage
+  spec.metadata["source_code_uri"]   = spec.homepage
+  spec.metadata["bug_tracker_uri"]   = "#{spec.homepage}/issues"
+  spec.metadata["changelog_uri"]     = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir[
+    "lib/**/*.rb",
+    "bin/*",
+    "prompts/*.md",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "docforge.gemspec"
+  ]
+  spec.bindir        = "bin"
+  spec.executables   = ["docforge"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "thor",        "~> 1.3"   # CLI
+  spec.add_dependency "caracal",     "~> 1.4"   # .docx generation
+  spec.add_dependency "httparty",    "~> 0.22"  # Anthropic API calls
+  spec.add_dependency "tty-prompt",  "~> 0.23"  # interview prompts
+  spec.add_dependency "tty-spinner", "~> 0.9"   # loader during API call
+
+  spec.add_development_dependency "rake", "~> 13.0"
+end

data/lib/docforge/brief.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Docforge
+  # Typed wrapper around the JSON payload the model returns.
+  # Gives the renderer a consistent API and lets us validate up front
+  # instead of crashing mid-render with a NoMethodError on `nil`.
+  class Brief
+    REQUIRED_KEYS = %w[
+      title value_statement problem_paragraph
+      capabilities worked_example design_decisions
+      why_hard_paragraph capabilities_table
+      sharable
+    ].freeze
+
+    attr_reader :data
+
+    def initialize(data)
+      @data = data
+      validate!
+    end
+
+    def title;             @data["title"]; end
+    def value_statement;   @data["value_statement"]; end
+    def pull_quote_italic; @data["pull_quote_italic"]; end
+    def metadata;          @data["metadata"] || {}; end
+    def problem;           @data["problem_paragraph"]; end
+    def capabilities;      @data["capabilities"] || []; end
+    def worked_example;    @data["worked_example"] || {}; end
+    def design_decisions;  @data["design_decisions"] || []; end
+    def why_hard;          @data["why_hard_paragraph"]; end
+    def capabilities_table; @data["capabilities_table"] || []; end
+    def numbers;           @data["numbers"] || []; end
+    def future_extensions; @data["future_extensions"] || []; end
+    def stack_and_credits; @data["stack_and_credits"] || {}; end
+    def sharable;          @data["sharable"] || {}; end
+
+    private
+
+    def validate!
+      missing = REQUIRED_KEYS - @data.keys
+      return if missing.empty?
+
+      raise InputError,
+        "Model response missing required keys: #{missing.join(', ')}.\n" \
+        "Got keys: #{@data.keys.inspect}"
+    end
+  end
+end

data/lib/docforge/cli.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "thor"
+require "tty-prompt"
+require "tty-spinner"
+require "json"
+require "time"
+require "fileutils"
+
+module Docforge
+  class CLI < Thor
+    package_name "docforge"
+
+    class_option :config, type: :string, aliases: "-c",
+      desc: "Path to a .docforge.yml config (overrides ./.docforge.yml)"
+
+    def self.exit_on_failure?
+      true
+    end
+
+    desc "version", "Print the gem version"
+    def version
+      puts Docforge::VERSION
+    end
+
+    desc "config", "Show current configuration"
+    def config
+      cfg = build_config
+      data = cfg.to_h
+      puts "docforge configuration"
+      puts "─" * 50
+      puts "  API key set:    #{data[:api_key_set] ? "yes" : "NO — set ANTHROPIC_API_KEY"}"
+      puts "  Model:          #{data[:model]}"
+      puts "  Output dir:     #{data[:output_dir]}"
+      puts "  Author:         #{data[:author]}"
+      puts "  Input files:    prd=#{data[:input_filenames]["prd"]}  spec=#{data[:input_filenames]["spec"]}  notes=#{data[:input_filenames]["notes"]}"
+      puts "  System prompt:  #{data[:system_prompt_path]}"
+      puts "  Interview qs:   #{data[:interview_question_count]}"
+      puts "  Loaded configs: #{data[:loaded_config_files].empty? ? "(none — using built-in defaults)" : data[:loaded_config_files].join(", ")}"
+    end
+
+    desc "init", "Write a starter .docforge.yml in the current directory"
+    option :force, type: :boolean, default: false, desc: "Overwrite an existing .docforge.yml"
+    def init
+      target = File.join(Dir.pwd, ".docforge.yml")
+      if File.exist?(target) && !options[:force]
+        warn "✗ #{target} already exists — pass --force to overwrite."
+        exit 1
+      end
+
+      File.write(target, starter_yaml)
+      puts "✓ Wrote #{target}"
+      puts "  Edit it to point at your project's PRD/SPEC filenames and (optionally) a custom prompt."
+    end
+
+    desc "generate FOLDER", "Generate a feature brief .docx from a folder containing PRD + SPEC"
+    option :no_interview, type: :boolean, default: false, desc: "Skip the interactive interview"
+    option :dry_run, type: :boolean, default: false, desc: "Show what would happen; skip API + render"
+    option :model, type: :string, desc: "Override ANTHROPIC_MODEL for this run"
+    option :fresh, type: :boolean, default: false, desc: "Ignore .brief-cache.json and re-call the API"
+    def generate(folder)
+      cfg = build_config
+      cfg.instance_variable_set(:@model, options[:model]) if options[:model]
+      cfg.validate! unless options[:dry_run] || cache_hit?(folder)
+
+      puts "→ Reading inputs from #{File.expand_path(folder)}"
+      if cfg.loaded_config_files.any?
+        puts "  · Config: #{cfg.loaded_config_files.join(", ")}"
+      end
+      inputs = Inputs.read(folder, config: cfg)
+      f = cfg.input_filenames
+      puts "  ✓ #{f["prd"]}  (#{inputs.prd.length} chars)"
+      puts "  ✓ #{f["spec"]} (#{inputs.spec.length} chars)"
+      puts "  #{inputs.notes ? "✓" : "·"} #{f["notes"]}  #{inputs.notes ? "(#{inputs.notes.length} chars)" : "(none)"}"
+      puts "  #{inputs.assets.any? ? "✓" : "·"} _assets/  (#{inputs.assets.size} files)"
+
+      cache_path = File.join(inputs.folder, ".brief-cache.json")
+      cached     = !options[:fresh] && File.exist?(cache_path)
+
+      if cached
+        puts "\n→ Using cached brief (#{cache_path})"
+        puts "  · pass --fresh to re-call the API"
+        cache_data = JSON.parse(File.read(cache_path, encoding: "UTF-8"))
+        payload    = cache_data["payload"]
+        puts "  ✓ Cached on #{cache_data["generated_at"]} via #{cache_data["model"]}"
+      else
+        interview_answers = options[:no_interview] ? {} : run_interview(cfg.interview_questions)
+        user_message = Prompt.user_message(inputs: inputs, interview_answers: interview_answers)
+
+        if options[:dry_run]
+          puts "\n→ DRY RUN — would call Anthropic with:"
+          puts "  Model:                 #{cfg.model}"
+          puts "  System prompt length:  #{Prompt.system_prompt(config: cfg).length} chars"
+          puts "  User message length:   #{user_message.length} chars"
+          puts "  Output would land at:  #{File.join(cfg.output_dir, inputs.slug)}.docx"
+          puts "\nSet ANTHROPIC_API_KEY and re-run without --dry-run to actually generate."
+          return
+        end
+
+        spinner = TTY::Spinner.new("[:spinner] Calling Anthropic (#{cfg.model})...", format: :dots)
+        spinner.auto_spin
+        begin
+          client  = Client.new(cfg)
+          payload = client.generate_brief(
+            system_prompt: Prompt.system_prompt(config: cfg),
+            user_message: user_message
+          )
+          spinner.success("(done)")
+        rescue StandardError => e
+          spinner.error("(failed)")
+          raise e
+        end
+
+        File.write(cache_path, JSON.pretty_generate(
+          "generated_at" => Time.now.utc.iso8601,
+          "model"        => cfg.model,
+          "payload"      => payload
+        ))
+        puts "  ✓ Cached response → #{cache_path}"
+      end
+
+      brief = Brief.new(payload)
+      puts "  ✓ Brief — #{brief.title.inspect}"
+
+      puts "\n→ Rendering .docx..."
+      path = Renderers::Docx.new(brief: brief, config: cfg, slug: inputs.slug).render
+      puts "  ✓ Wrote #{path}"
+      puts "\nDone. Open it: open \"#{path}\""
+    rescue Error => e
+      warn "ERROR: #{e.message}"
+      exit 1
+    end
+
+    private
+
+    def build_config
+      Config.new(explicit_config_path: options[:config])
+    end
+
+    def cache_hit?(folder)
+      return false if options[:fresh]
+      File.exist?(File.join(File.expand_path(folder), ".brief-cache.json"))
+    end
+
+    def run_interview(questions)
+      prompt = TTY::Prompt.new
+      prompt.say "\nInterview (#{questions.size} questions — press Enter to skip any single one)"
+      prompt.say "─" * 40
+
+      answers = {}
+      questions.each_with_index do |q, i|
+        ans = prompt.ask("[#{i + 1}/#{questions.size}] #{q}")
+        answers[q] = ans unless ans.nil? || ans.strip.empty?
+      end
+      answers
+    end
+
+    def starter_yaml
+      <<~YAML
+        # docforge project configuration
+        # Values here override ~/.docforge.yml. Env vars override these.
+
+        # Anthropic model (env: ANTHROPIC_MODEL)
+        model: claude-sonnet-4-5
+
+        # Where the generated .docx lands (env: DOCFORGE_OUTPUT_DIR)
+        output_dir: ~/Desktop/Portfolio/Features
+
+        # Byline on the brief (env: DOCFORGE_AUTHOR)
+        author: Your Name
+
+        # Input filenames docforge looks for inside each feature folder
+        input_files:
+          prd: PRD.md
+          spec: SPEC.md
+          notes: notes.md
+
+        # Path to a custom system prompt (relative to this yaml).
+        # Comment out to use the gem's bundled prompt.
+        # system_prompt: ./prompts/feature_brief.md
+
+        # Override the interview questions asked before generation.
+        # Leave commented out to use the defaults.
+        # interview:
+        #   - "Who is the human user of this feature?"
+        #   - "What was the world like before this shipped?"
+        #   - "What was the single hardest design decision, and why?"
+      YAML
+    end
+  end
+end

data/lib/docforge/client.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "httparty"
+require "json"
+
+module Docforge
+  # Thin wrapper around the Anthropic Messages API.
+  # Docs: https://docs.anthropic.com/en/api/messages
+  #
+  # We use *tool-use forcing* to guarantee a structurally valid JSON payload.
+  # Free-form text responses occasionally include unescaped quotes inside
+  # long string values; tool_use bypasses that entirely because the API
+  # validates the tool input against a JSON schema before returning.
+  class Client
+    include HTTParty
+    base_uri "https://api.anthropic.com"
+
+    API_VERSION = "2023-06-01"
+    MAX_TOKENS  = 8000
+    TOOL_NAME   = "emit_brief"
+    RAW_DUMP    = "/tmp/docforge-last-response.json"
+
+    def initialize(config)
+      @config = config
+    end
+
+    def generate_brief(system_prompt:, user_message:)
+      body = {
+        model: @config.model,
+        max_tokens: MAX_TOKENS,
+        system: system_prompt,
+        tools: [{
+          name: TOOL_NAME,
+          description: "Emit the structured feature brief.",
+          input_schema: { type: "object", additionalProperties: true }
+        }],
+        tool_choice: { type: "tool", name: TOOL_NAME },
+        messages: [{ role: "user", content: user_message }]
+      }
+
+      response = self.class.post(
+        "/v1/messages",
+        headers: {
+          "x-api-key" => @config.api_key,
+          "anthropic-version" => API_VERSION,
+          "content-type" => "application/json"
+        },
+        body: body.to_json,
+        timeout: 120
+      )
+
+      raise ApiError, "Anthropic API #{response.code}: #{response.body}" unless response.success?
+
+      # Dump raw response immediately so tokens are never wasted on a parse fail.
+      begin
+        File.write(RAW_DUMP, JSON.pretty_generate(response.parsed_response))
+      rescue StandardError
+        # best-effort
+      end
+
+      extract_tool_input(response.parsed_response)
+    end
+
+    private
+
+    def extract_tool_input(parsed)
+      blocks = Array(parsed["content"])
+      tool_block = blocks.find { |b| b["type"] == "tool_use" && b["name"] == TOOL_NAME }
+
+      if tool_block && tool_block["input"].is_a?(Hash)
+        return tool_block["input"]
+      end
+
+      # Fallback: older response shapes or refusal text — try text parsing.
+      text = blocks.find { |b| b["type"] == "text" }&.dig("text")
+      raise ApiError, "No tool_use block in response. Raw dumped to #{RAW_DUMP}" if text.nil? || text.strip.empty?
+
+      cleaned = text.strip.sub(/\A```(?:json)?\s*/, "").sub(/\s*```\z/, "")
+      JSON.parse(cleaned)
+    rescue JSON::ParserError => e
+      raise ApiError, "Model did not return valid JSON: #{e.message}\nRaw response saved to #{RAW_DUMP}"
+    end
+  end
+end

data/lib/docforge/config.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Docforge
+  # Layered configuration.
+  #
+  # Precedence (highest wins):
+  #   1. ENV vars
+  #   2. Project config (./.docforge.yml, or --config PATH)
+  #   3. Global config (~/.docforge.yml)
+  #   4. Built-in defaults
+  #
+  # Env vars:
+  #   ANTHROPIC_API_KEY   — required, your Anthropic API key
+  #   ANTHROPIC_MODEL     — model id (overrides yaml `model`)
+  #   DOCFORGE_OUTPUT_DIR — where briefs are written
+  #   DOCFORGE_AUTHOR     — byline on the brief
+  #
+  # YAML schema (all keys optional — see `docforge init` for a template):
+  #
+  #   model: claude-sonnet-4-5
+  #   output_dir: ~/Desktop/Portfolio/Features
+  #   author: Your Name
+  #   input_files:
+  #     prd: PRD.md
+  #     spec: SPEC.md
+  #     notes: notes.md
+  #   system_prompt: ./prompts/feature_brief.md   # relative to this yaml
+  #   interview:
+  #     - "Who is the human user of this feature?"
+  #     - "..."
+  class Config
+    DEFAULT_MODEL      = "claude-sonnet-4-5"
+    DEFAULT_OUTPUT_DIR = File.expand_path("~/Desktop/Portfolio/Features")
+    DEFAULT_AUTHOR     = "You"
+    DEFAULT_INPUT_FILES = { "prd" => "PRD.md", "spec" => "SPEC.md", "notes" => "notes.md" }.freeze
+    DEFAULT_INTERVIEW = [
+      "Who is the human user of this feature? Name them (e.g. 'Mira, a content designer at an EdTech client').",
+      "What was the world like *before* this shipped — specifically?",
+      "What was the single hardest design decision, and why?",
+      "What's the one metric you'd brag about (or a design target if pre-production)?",
+      "Is there a moment in the build that taught you something worth conveying?"
+    ].freeze
+    BUNDLED_SYSTEM_PROMPT_PATH = File.expand_path("../../prompts/system_prompt.md", __dir__)
+
+    GLOBAL_CONFIG_PATH  = File.expand_path("~/.docforge.yml")
+    PROJECT_CONFIG_NAME = ".docforge.yml"
+
+    attr_reader :api_key, :model, :output_dir, :author,
+                :input_filenames, :interview_questions,
+                :system_prompt_path, :loaded_config_files
+
+    def initialize(env: ENV, explicit_config_path: nil, cwd: Dir.pwd)
+      @loaded_config_files = []
+
+      global  = load_yaml(GLOBAL_CONFIG_PATH)
+      project = load_yaml(explicit_config_path || File.join(cwd, PROJECT_CONFIG_NAME))
+      merged  = global.merge(project)
+
+      @api_key    = env["ANTHROPIC_API_KEY"]
+      @model      = env["ANTHROPIC_MODEL"]      || merged["model"]      || DEFAULT_MODEL
+      @output_dir = env["DOCFORGE_OUTPUT_DIR"]  || merged["output_dir"] || DEFAULT_OUTPUT_DIR
+      @author     = env["DOCFORGE_AUTHOR"]      || merged["author"]     || DEFAULT_AUTHOR
+      @output_dir = File.expand_path(@output_dir)
+
+      @input_filenames = DEFAULT_INPUT_FILES.merge(merged["input_files"] || {})
+      @interview_questions = Array(merged["interview"]).then { |a| a.empty? ? DEFAULT_INTERVIEW : a }
+      @system_prompt_path  = resolve_system_prompt_path(merged["system_prompt"], merged["_loaded_from"])
+    end
+
+    def system_prompt_content
+      @system_prompt_content ||= File.read(@system_prompt_path)
+    end
+
+    def validate!
+      if api_key.nil? || api_key.strip.empty?
+        raise ConfigError, <<~MSG
+          ANTHROPIC_API_KEY is not set.
+          Get one at https://console.anthropic.com/settings/keys and export it:
+            export ANTHROPIC_API_KEY=sk-ant-...
+        MSG
+      end
+      unless File.exist?(@system_prompt_path)
+        raise ConfigError, "System prompt file not found: #{@system_prompt_path}"
+      end
+      true
+    end
+
+    def to_h
+      {
+        api_key_set: !api_key.nil? && !api_key.empty?,
+        model: model,
+        output_dir: output_dir,
+        author: author,
+        input_filenames: input_filenames,
+        system_prompt_path: system_prompt_path,
+        interview_question_count: interview_questions.size,
+        loaded_config_files: loaded_config_files
+      }
+    end
+
+    private
+
+    def load_yaml(path)
+      return {} unless path && File.exist?(path)
+      data = YAML.safe_load_file(path, permitted_classes: [Symbol]) || {}
+      @loaded_config_files << path
+      data["_loaded_from"] = path
+      data
+    end
+
+    # Resolve system_prompt path relative to the yaml file that defined it,
+    # so a project-local yaml can point at a project-local prompt.
+    def resolve_system_prompt_path(value, yaml_path)
+      return BUNDLED_SYSTEM_PROMPT_PATH if value.nil? || value.to_s.strip.empty?
+      base = yaml_path ? File.dirname(yaml_path) : Dir.pwd
+      File.expand_path(value, base)
+    end
+  end
+end

data/lib/docforge/inputs.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Docforge
+  # Reads a feature folder. Default layout:
+  #
+  #   <folder>/
+  #     PRD.md     (required — name configurable via input_files.prd)
+  #     SPEC.md    (required — name configurable via input_files.spec)
+  #     notes.md   (optional — name configurable via input_files.notes)
+  #     _assets/   (optional)
+  class Inputs
+    attr_reader :folder, :prd, :spec, :notes, :assets, :config
+
+    def self.read(path, config: Config.new)
+      new(path, config: config).tap(&:load!)
+    end
+
+    def initialize(path, config: Config.new)
+      @folder = File.expand_path(path)
+      @config = config
+    end
+
+    def load!
+      raise InputError, "Folder not found: #{folder}" unless File.directory?(folder)
+
+      prd_name   = config.input_filenames["prd"]
+      spec_name  = config.input_filenames["spec"]
+      notes_name = config.input_filenames["notes"]
+
+      prd_path  = locate(prd_name)
+      spec_path = locate(spec_name)
+      raise InputError, "#{prd_name} not found in #{folder}"  unless prd_path
+      raise InputError, "#{spec_name} not found in #{folder}" unless spec_path
+
+      @prd    = File.read(prd_path)
+      @spec   = File.read(spec_path)
+      notes_p = notes_name ? locate(notes_name) : nil
+      @notes  = notes_p ? File.read(notes_p) : nil
+      @assets = locate_assets
+      self
+    end
+
+    def slug
+      File.basename(folder).downcase.gsub(/[^a-z0-9-]+/, "-").gsub(/^-|-$/, "")
+    end
+
+    private
+
+    def locate(filename)
+      direct = File.join(folder, filename)
+      return direct if File.exist?(direct)
+      Dir.glob(File.join(folder, "*", filename)).first
+    end
+
+    def locate_assets
+      assets_dir = File.join(folder, "_assets")
+      return [] unless File.directory?(assets_dir)
+      Dir.glob(File.join(assets_dir, "*")).select { |p| File.file?(p) }.sort
+    end
+  end
+end

data/lib/docforge/prompt.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Docforge
+  # Builds the user message wrapping the feature's inputs (PRD, SPEC, notes,
+  # asset list). The system prompt itself is resolved through Config so it
+  # can be overridden per-project.
+  module Prompt
+    module_function
+
+    def system_prompt(config:)
+      config.system_prompt_content
+    end
+
+    def user_message(inputs:, interview_answers: {})
+      <<~MSG
+        ## PRD
+
+        #{inputs.prd}
+
+        ---
+
+        ## SPEC
+
+        #{inputs.spec}
+
+        #{notes_section(inputs)}
+        #{interview_section(interview_answers)}
+        #{assets_section(inputs)}
+      MSG
+    end
+
+    def notes_section(inputs)
+      return "" unless inputs.notes
+      <<~SECTION
+
+        ---
+
+        ## Author's notes ("what I'm most proud of")
+
+        #{inputs.notes}
+      SECTION
+    end
+
+    def interview_section(answers)
+      return "" if answers.nil? || answers.empty?
+
+      lines = answers.map { |q, a| "**Q: #{q}**\nA: #{a}" }.join("\n\n")
+      <<~SECTION
+
+        ---
+
+        ## Interview answers
+
+        #{lines}
+      SECTION
+    end
+
+    def assets_section(inputs)
+      return "" if inputs.assets.empty?
+
+      list = inputs.assets.map { |p| "- #{File.basename(p)}" }.join("\n")
+      <<~SECTION
+
+        ---
+
+        ## Available assets (filenames you may reference)
+
+        #{list}
+      SECTION
+    end
+  end
+end

data/lib/docforge/renderers/docx.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require "caracal"
+require "fileutils"
+
+module Docforge
+  module Renderers
+    # Renders a Brief to a styled .docx using caracal.
+    #
+    # Visual language: "modern tech" — sans-serif throughout, one blue
+    # accent, table-heavy, generous whitespace, callout boxes for the
+    # pull quote and sharable footer.
+    class Docx
+      ACCENT      = "2563eb"  # blue
+      NEUTRAL_700 = "374151"
+      NEUTRAL_500 = "6b7280"
+      NEUTRAL_200 = "e5e7eb"
+      CALLOUT_BG  = "f8fafc"
+
+      def initialize(brief:, config:, slug:)
+        @brief  = brief
+        @config = config
+        @slug   = slug
+      end
+
+      def render
+        FileUtils.mkdir_p(@config.output_dir)
+        path = File.join(@config.output_dir, "#{@slug}.docx")
+        b = @brief
+        renderer = self
+        Caracal::Document.save(path) do |doc|
+          doc.font name: "Calibri"
+          doc.page_margins do
+            top    1080  # 0.75"
+            bottom 1080
+            left   1080
+            right  1080
+          end
+
+          renderer.send(:render_cover, doc, b)
+          doc.page
+
+          renderer.send(:render_problem, doc, b)
+          renderer.send(:render_capabilities, doc, b)
+          renderer.send(:render_worked_example, doc, b)
+          renderer.send(:render_how_it_works, doc, b)
+          renderer.send(:render_capabilities_table, doc, b)
+          renderer.send(:render_numbers, doc, b)
+          renderer.send(:render_future, doc, b)
+          renderer.send(:render_stack, doc, b)
+
+          doc.page
+          renderer.send(:render_sharable, doc, b)
+        end
+        path
+      end
+
+      private
+
+      def render_cover(doc, b)
+        doc.p
+        doc.h1 b.title, color: NEUTRAL_700, size: 44
+        doc.p b.value_statement, size: 26, color: ACCENT, italic: false
+        doc.hr line: "single", color: ACCENT, size: 8
+        doc.p
+        doc.p b.pull_quote_italic.to_s, italic: true, size: 22, color: NEUTRAL_500
+        doc.p
+        render_metadata_table(doc, b.metadata)
+      end
+
+      def render_metadata_table(doc, meta)
+        data = []
+        data << ["Built for",    meta["built_for"].to_s]    if meta["built_for"]
+        data << ["Shipped",      meta["shipped"].to_s]      if meta["shipped"]
+        data << ["Reading time", meta["reading_time"].to_s] if meta["reading_time"]
+        data << ["Tags",         Array(meta["tags"]).join(" · ")] if meta["tags"]
+
+        return if data.empty?
+
+        neutral_500 = NEUTRAL_500
+        neutral_700 = NEUTRAL_700
+
+        doc.table(data, border_size: 0, width: 9000) do
+          cell_style cols[0], color: neutral_500, size: 18, bold: true
+          cell_style cols[1], color: neutral_700, size: 18
+        end
+      end
+
+      def render_problem(doc, b)
+        section_heading(doc, "The problem")
+        doc.p b.problem.to_s, size: 22, color: NEUTRAL_700
+      end
+
+      def render_capabilities(doc, b)
+        section_heading(doc, "What the feature does")
+        b.capabilities.each do |cap|
+          doc.p do
+            text "#{cap['name']}", bold: true, color: ACCENT, size: 22
+            text " — #{cap['description']}", size: 22, color: NEUTRAL_700
+          end
+        end
+      end
+
+      def render_worked_example(doc, b)
+        section_heading(doc, "Worked example")
+        we = b.worked_example
+        if we["persona_name"]
+          doc.p "Meet #{we['persona_name']}.", bold: true, color: NEUTRAL_700, size: 22
+        end
+        Array(we["story_paragraphs"]).each do |para|
+          doc.p para.to_s, size: 22, color: NEUTRAL_700
+        end
+      end
+
+      def render_how_it_works(doc, b)
+        section_heading(doc, "How it works")
+
+        data = [["Decision", "Chosen approach", "Why not the alternative"]]
+        b.design_decisions.each do |d|
+          data << [d["decision"].to_s, d["chosen"].to_s, d["alternative_rejection"].to_s]
+        end
+
+        accent      = ACCENT
+        neutral_700 = NEUTRAL_700
+
+        doc.table(data, border_color: NEUTRAL_200, border_size: 4, width: 9000) do
+          cell_style rows[0], background: accent, color: "ffffff", bold: true, size: 20
+          cell_style rows[1..], size: 18, color: neutral_700
+        end
+
+        doc.p
+        sub_heading(doc, "Why this is hard")
+        doc.p b.why_hard.to_s, size: 22, color: NEUTRAL_700
+      end
+
+      def render_capabilities_table(doc, b)
+        section_heading(doc, "Capabilities this demonstrates")
+
+        data = [["Capability", "Where it shows up here"]]
+        b.capabilities_table.each do |c|
+          data << [c["capability"].to_s, c["proof"].to_s]
+        end
+
+        accent      = ACCENT
+        neutral_700 = NEUTRAL_700
+
+        doc.table(data, border_color: NEUTRAL_200, border_size: 4, width: 9000) do
+          cell_style rows[0], background: accent, color: "ffffff", bold: true, size: 20
+          cell_style rows[1..], size: 18, color: neutral_700
+        end
+      end
+
+      def render_numbers(doc, b)
+        return if b.numbers.empty?
+
+        section_heading(doc, "Numbers & outcomes")
+        b.numbers.each do |n|
+          doc.p do
+            text "#{n['label']}: ", bold: true, color: NEUTRAL_500, size: 22
+            text n["value"].to_s, color: NEUTRAL_700, size: 22
+          end
+        end
+      end
+
+      def render_future(doc, b)
+        return if b.future_extensions.empty?
+
+        section_heading(doc, "What could be added")
+        b.future_extensions.each do |ext|
+          doc.ul style: "ListBullet" do
+            li ext.to_s, size: 22, color: NEUTRAL_700
+          end
+        end
+      end
+
+      def render_stack(doc, b)
+        sc = b.stack_and_credits
+        return if sc.empty?
+
+        section_heading(doc, "Stack & credits")
+        doc.p do
+          text "Stack: ", bold: true, color: NEUTRAL_500, size: 20
+          text sc["stack"].to_s, color: NEUTRAL_700, size: 20
+        end
+        if sc["role"]
+          doc.p do
+            text "Role: ", bold: true, color: NEUTRAL_500, size: 20
+            text sc["role"].to_s, color: NEUTRAL_700, size: 20
+          end
+        end
+        if sc["further_reading"]
+          doc.p do
+            text "Further reading: ", bold: true, color: NEUTRAL_500, size: 20
+            text sc["further_reading"].to_s, color: NEUTRAL_700, size: 20
+          end
+        end
+      end
+
+      def render_sharable(doc, b)
+        s = b.sharable
+        doc.h2 "Sharable extras", color: ACCENT, size: 28
+
+        if s["linkedin_summary"]
+          sub_heading(doc, "LinkedIn-ready summary")
+          doc.p s["linkedin_summary"].to_s, size: 22, color: NEUTRAL_700
+        end
+
+        if s["pull_quote_short"]
+          sub_heading(doc, "Pull quote")
+          doc.p s["pull_quote_short"].to_s, italic: true, size: 22, color: ACCENT
+        end
+
+        if Array(s["alt_titles"]).any?
+          sub_heading(doc, "Alternative title lines")
+          s["alt_titles"].each do |t|
+            doc.ul style: "ListBullet" do
+              li t.to_s, size: 22, color: NEUTRAL_700
+            end
+          end
+        end
+
+        doc.p
+        doc.p "Generated by docforge.", size: 16, color: NEUTRAL_500, italic: true
+      end
+
+      def section_heading(doc, text)
+        doc.p
+        doc.h2 text, color: NEUTRAL_700, size: 28
+        doc.hr line: "single", color: NEUTRAL_200, size: 4
+        doc.p
+      end
+
+      def sub_heading(doc, text)
+        doc.p text, bold: true, color: NEUTRAL_500, size: 22
+      end
+    end
+  end
+end

data/lib/docforge/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Docforge
+  VERSION = "0.1.0"
+end

data/lib/docforge.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "docforge/version"
+require_relative "docforge/config"
+require_relative "docforge/inputs"
+require_relative "docforge/prompt"
+require_relative "docforge/client"
+require_relative "docforge/brief"
+require_relative "docforge/renderers/docx"
+
+module Docforge
+  class Error < StandardError; end
+  class ConfigError < Error; end
+  class InputError < Error; end
+  class ApiError < Error; end
+end

data/prompts/system_prompt.md

@@ -0,0 +1,101 @@
+# Feature Brief Writer — System Prompt
+
+You are a portfolio writer helping the user produce a client-facing brief
+for a feature they built. The brief lives in their personal portfolio. Its
+job is to make a non-technical buyer say "I want this team to build for
+me" within 10 minutes of reading, while a CTO who skims the back half
+walks away thinking "this person is serious."
+
+## Inputs
+
+You will receive a PRD describing the user-facing problem and acceptance
+criteria, a SPEC describing the implementation, optionally a short notes
+file ("what I'm most proud of"), and optionally a list of available asset
+filenames (screenshots, diagrams) you can reference.
+
+## Output contract — STRICT
+
+Return **valid JSON only** matching this schema. No prose around it, no
+markdown code fences, no explanation. The CLI parses your response with
+`JSON.parse` and any extra text will crash it.
+
+```
+{
+  "title": "string — feature name (e.g. 'Branchable Dialog Trees')",
+  "value_statement": "string — one sentence in buyer language",
+  "pull_quote_italic": "string — opening italic quote, a moment in a named persona's life",
+  "metadata": {
+    "built_for": "string",
+    "shipped": "string (Month YYYY)",
+    "reading_time": "string (e.g. '~10 min')",
+    "tags": ["string", "string", "..."]
+  },
+  "problem_paragraph": "string — single paragraph, ~80 words, ends with a hook",
+  "capabilities": [
+    { "name": "string — bold short label", "description": "string — one sentence" }
+  ],
+  "worked_example": {
+    "persona_name": "string",
+    "story_paragraphs": ["string", "string", "string"]
+  },
+  "design_decisions": [
+    {
+      "decision": "string — short title",
+      "chosen": "string — one-line summary of what was picked",
+      "alternative_rejection": "string — one-line rebuttal of the obvious alternative"
+    }
+  ],
+  "why_hard_paragraph": "string — one paragraph on the non-obvious technical problems solved",
+  "capabilities_table": [
+    { "capability": "string", "proof": "string — one line, where it shows up here" }
+  ],
+  "numbers": [
+    { "label": "string", "value": "string" }
+  ],
+  "future_extensions": ["string", "string"],
+  "stack_and_credits": {
+    "stack": "string — comma-separated tech list",
+    "role": "string — what the user did",
+    "further_reading": "string — links / 'on request'"
+  },
+  "sharable": {
+    "linkedin_summary": "string — ≤80 words",
+    "pull_quote_short": "string — one sentence email-signature ready",
+    "alt_titles": ["string", "string", "string"]
+  }
+}
+```
+
+## Voice rules
+
+- Confident, not boastful. "We replaced X with Y" beats "We pioneered…".
+- Examples over abstractions. The worked example is the highest-leverage
+  section.
+- Jargon-light in the first half (problem, capabilities, worked example),
+  technically precise in the back half (decisions, why-hard, capabilities
+  table).
+- Specific numbers always beat ranges. Never invent a number — if the
+  inputs don't contain it, omit it. The `numbers` array can be short.
+- No filler. Cut every sentence that doesn't earn its place.
+- 1,500–2,000 words total across all fields.
+
+## Things to do
+
+- Pick a single named persona for the worked example. Invent the name if
+  the inputs don't supply one (Mira, Sam, Priya — short, neutral).
+- Pick 3 design decisions. Maximum 5. Never more.
+- Pick 4–6 capabilities for the capabilities table. Map each to a
+  concrete proof point from the SPEC.
+- For `pull_quote_italic`, write a one-sentence "moment in time" — a
+  timestamped action, an elapsed-time number, something cinematic. Avoid
+  generic value statements.
+
+## Things to skip
+
+- Don't explain every implementation detail. The SPEC has that.
+- Don't list every file touched.
+- Don't apologize, hedge, or use "essentially" / "basically".
+- Don't compare to competitors.
+- Don't fabricate metrics, dates, or client names.
+
+Begin. Return JSON only.

metadata

@@ -0,0 +1,156 @@
+--- !ruby/object:Gem::Specification
+name: docforge
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Rao Usama Abid
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: caracal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: tty-prompt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.23'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.23'
+- !ruby/object:Gem::Dependency
+  name: tty-spinner
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: |
+  docforge reads a feature folder containing a PRD and a SPEC, calls
+  the Anthropic API with a saved feature-brief writer prompt, and emits
+  a styled .docx ready to share with non-technical readers (clients,
+  portfolios, internal stakeholders).
+
+  Configurable per-project via .docforge.yml: input filenames, system
+  prompt, interview questions, output directory, and model.
+email:
+- usamaroar786@gmail.com
+executables:
+- docforge
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- bin/docforge
+- docforge.gemspec
+- lib/docforge.rb
+- lib/docforge/brief.rb
+- lib/docforge/cli.rb
+- lib/docforge/client.rb
+- lib/docforge/config.rb
+- lib/docforge/inputs.rb
+- lib/docforge/prompt.rb
+- lib/docforge/renderers/docx.rb
+- lib/docforge/version.rb
+- prompts/system_prompt.md
+homepage: https://github.com/RaoUsamaAbid/docforge
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/RaoUsamaAbid/docforge
+  source_code_uri: https://github.com/RaoUsamaAbid/docforge
+  bug_tracker_uri: https://github.com/RaoUsamaAbid/docforge/issues
+  changelog_uri: https://github.com/RaoUsamaAbid/docforge/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Generate client-facing feature briefs (.docx) from a PRD + SPEC pair using
+  Claude.
+test_files: []