qtr: Deterministic Project Quoter & Proposal Generator

qtr is a high-speed, deterministic command-line quoter and executive proposal generator built in Crystal for systems infrastructure engineering consultancies.

It replaces ad-hoc guesswork and conversational estimation drift with codified infrastructure archetypes, deterministic sizing rules, transparent rate matrices, and multi-format document generation (reStructuredText, Markdown, vector PDF, and structured JSON).

---

Key Features

• Declarative Sizing Archetypes: Codified workload estimation and sizing manifests that mathematically compute hours and costs across discovery, provisioning, migration/development, runbook documentation, and post-go-live hypercare.
• Tiered Rate Matrix: Built-in support for differentiated service rates (e.g., $75.00 USD/hr standard sysadmin/DevOps versus $130.00 USD/hr specialized virtualization/migration), currency conversion to MXN, configurable tax (I.V.A. 16%), payment milestones (50/50, 40/30/30), and 12-month installment financing (+20%).
• Multi-Format Document Pipeline:
  • reStructuredText (.rst): Native format calibrated for standard document publishing pipelines.
  • Markdown (.md): CommonMark/GFM format suitable for GitLab/GitHub repositories and wikis.
  • Standalone Vector PDF (.pdf): 100% native compilation via pure Crystal (pdf.cr) with embedded DejaVu Sans TrueType fonts, user-provided custom font loading (--font), corporate logo support, alternating table grids, and two-pass dynamic page numbering. Zero runtime CLI dependencies (no Pandoc, no LaTeX, no TeX Live). Legacy Pandoc/LaTeX support remains accessible via --pdf-engine=pandoc.
  • JSON (.json): Machine-readable data structure for automated agentic toolchains.
• Embedded External Templates & Fonts: Templates and TrueType fonts reside in templates/ and assets/fonts/ for clean development, but are compiled directly into the binary at build time. Produces a single, self-contained executable.
• Hierarchical Configuration & Delimiters: Three-tier configuration cascade (CLI flags > Environment Variables > YAML config file > Defaults). All YAML documents strictly enforce --- start and ... end markers.
• Antigravity AI Skill: Built-in skill definition enabling AI pair programmers to size and emit proposals programmatically.

---

Installation & Building

Prerequisites

• Crystal >= 1.21.1
• Shards
• GNU Make

Build from Source

git clone https://gitlab.com/renich/qtr.git
cd qtr
make deps
make build

The compiled binary will be placed in bin/qtr.

Installation

To install both the binary (~/.local/bin/qtr) and the Antigravity agent skill (~/.gemini/config/skills/qtr/SKILL.md):

make install-user

Or for system-wide installation to /usr/local:

sudo make install

---

Agent Skill Integration (.agents/skills/qtr)

The repository includes a dedicated Antigravity AI Agent Skill located at: .agents/skills/qtr/SKILL.md

Instructions for AI Agents

If you are an autonomous coding agent working in this repository and need to install or update the qtr skill into your active agent configuration:

1. Via Makefile:

   make install-skill

2. Via Direct Copy:

   mkdir -p ~/.gemini/config/skills/qtr
   cp .agents/skills/qtr/SKILL.md ~/.gemini/config/skills/qtr/SKILL.md

3. Via Symlink (recommended for active skill development):

   mkdir -p ~/.gemini/config/skills
   ln -sfn "$(pwd)/.agents/skills/qtr" ~/.gemini/config/skills/qtr

When active, the agent uses qtr to generate mathematically deterministic infrastructure quotes without calculation drift, hallucinated arithmetic, or missing operational phases.

---

Quick Usage

1. Generate a Quote from a Declarative Manifest

# Generate all formats (RST, Markdown, JSON) and standalone native PDF
qtr manifests/sample_web_and_ai.yml \
  --client="Acme Corp" \
  --format=all \
  --out="./proposals/web-and-ai" \
  --build-pdf

2. Standalone Native PDF with Custom TrueType Font

qtr manifests/sample_vmware_migration.yml \
  --format=pdf \
  --font="/usr/share/fonts/dejavu-sans-fonts/DejaVuSans.ttf" \
  --out="./proposals/vmware-migration.pdf"

3. Inspect Active Rates & Configuration

qtr config

4. Output as Structured JSON for AI Agents/Automation

qtr manifests/sample_web_and_ai.yml --format=json

---

Configuration

qtr searches for configuration files at:

1. File passed via --config=<path>
2. ./qtr.yaml
3. ~/.config/qtr/config.yaml

All configuration files enforce --- start and ... end document delimiters.

Example ~/.config/qtr/config.yaml:

---
organization:
  name: "Consulting Services"
  site: "https://example.com/"
  copyright: "All rights reserved. Consulting Services. CC-BY-SA 4.0 or later."

contact:
  name: "Consultant"
  email: "consultant@example.com"
  phone: "+1 (555) 000-0000"
  telegram: "https://t.me/example"
  location: "Remote"

rates:
  standard: 75.0
  specialized_virtualization: 130.0
  architecture_consulting: 130.0

currency:
  default: "USD"
  exchange_rate_usd_mxn: 19.50
  tax_rate: 0.16

pdf:
  engine: "native"
  font: "/path/to/custom-font.ttf"
  font_regular: "/path/to/custom-regular.ttf"
  font_bold: "/path/to/custom-bold.ttf"
...

---

Documentation

Comprehensive project specifications are located in the docs/ tree following the spec-standard:

• Business Specification
• Functional Specification
• Technical Specification
• Architecture Decision Records (ADRs)

---

Development & Testing

make check   # Runs specs, linters, and doc checks
make lint    # Runs static analysis (Ameba & Flaw)
make format  # Formats code (crystal tool format)

---

Licensing

• Software Code: Licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later).
• Documentation: Licensed under the GNU Free Documentation License v1.3 or later without Invariant Sections (GFDL-1.3-or-later).