Progress Report Generator
Generate professional PDF progress reports with live screenshots, metrics, and charts.
Workflow
- Determine report scope (full project / feature / sprint)
- Gather metrics from the codebase
- Capture dashboard screenshots via agent-browser
- Build the HTML report from the template
- Generate PDF via
agent-browser pdf
- Save to
docs/reports/ with date-stamped filename
Step 1: Determine Report Scope
Ask the user which scope they want if not specified via ARGUMENTS:
Full Project — All phases, architecture, security, DB schema, roadmap, engineering metrics, dashboard screenshots. For stakeholder updates, investor decks, milestone reviews.
Feature / Phase — Single feature or phase. What was built, implementation stats, relevant screenshots. For sprint reviews or feature demos.
Sprint / Weekly — Recent work summary. Commits, files changed, key metrics. For team standups or weekly updates.
Step 2: Gather Metrics
Run these to collect data. Adapt commands to the project's actual structure.
# LOC (exclude generated dirs)
find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.rs" \) \
-not -path "*/node_modules/*" -not -path "*/target/*" -not -path "*/.next/*" \
-not -path "*/dist/*" | xargs wc -l | tail -1
# Per-language
find . -type f \( -name "*.ts" -o -name "*.tsx" \) -not -path "*/node_modules/*" -not -path "*/.next/*" | xargs wc -l | tail -1
find . -type f -name "*.rs" -not -path "*/target/*" | xargs wc -l | tail -1
# Source file count
find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.rs" \) \
-not -path "*/node_modules/*" -not -path "*/target/*" -not -path "*/.next/*" | wc -l
# Git stats
git log --oneline | wc -l
git log --oneline --since="7 days ago"
git diff --shortstat main...HEAD
# Tests (adapt to project)
cargo test --manifest-path apps/agent/Cargo.toml 2>&1 | grep "test result"
bun test 2>&1 | grep -E "pass|fail"
# DB tables
grep -rl "pgTable\|createTable" packages/db/src/schema/ | wc -l
# Dashboard pages
find apps/dashboard/src/app -name "page.tsx" | wc -l
# API routes
find apps/api/src/routes -name "*.ts" | wc -l
Read CLAUDE.md, package.json, Cargo.toml to understand the stack before running.
Step 3: Capture Screenshots
Use agent-browser CLI to capture live dashboard screenshots.
mkdir -p docs/reports/screenshots
agent-browser open http://localhost:3000/login
agent-browser snapshot -i
# Fill login form (adapt refs to actual form)
agent-browser fill @e1 "[email protected]"
agent-browser fill @e2 "password"
agent-browser click @e3
agent-browser wait 2000
# Capture pages
agent-browser open http://localhost:3000
agent-browser wait 2000
agent-browser screenshot --full docs/reports/screenshots/overview.png
# Repeat for each relevant page...
agent-browser close
Guidelines:
- Wait 2s after navigation for data to load
- Use
--full for scrollable pages, viewport for single-screen pages
- Save to
docs/reports/screenshots/ (sibling to the HTML)
- Reference in HTML as
screenshots/filename.png (relative path)
- Full project: 4-6 screenshots. Feature: 1-3. Sprint: 1-2.
Step 4: Build the HTML Report
Copy the CSS template from [assets/report-template.html](assets/report-template.html) as the starting point. It contains all the pre-built CSS classes. Populate sections based on report scope.
Critical Rules
- Hardcoded hex colors only — NEVER use CSS variables (
var()). They cause invisible text in PDF.
- System fonts:
-apple-system, BlinkMacSystemFont, 'Helvetica Neue', Arial, sans-serif
- Page breaks:
page-break-before: always between sections, page-break-inside: avoid on cards/tables/screenshots
- Relative image paths:
screenshots/name.png
Design System
The template includes a 6-color brand system documented at the top of the CSS. To adapt to a project's branding, check CLAUDE.md, tailwind.config, or globals.css for brand colors and replace the 6 hex values throughout.
Section Reference
See [references/sections-guide.md](references/sections-guide.md) for copy-paste HTML snippets for all 20 components:
Layout & Structure: Cover page, section headers, back cover, page breaks, two/three-column layouts Data Display: KPI row (hero numbers), stat cards (4 variants), tables (dark/light header), mini stat boxes Visualization: Bar charts, donut charts (CSS conic-gradient), progress bars, badges (7 colors) Content: Feature cards (2-col grid with icons), checkmark lists, numbered layers, callout boxes Narrative: Timeline (with done/pending states), comparison cards (before/after), screenshots with captions
Read the sections-guide when building the HTML. It includes a color palette reference table and icon/entity combos.
Sections by Scope
Full Project: Cover → Executive Summary → Architecture → Phase Deliverables → Current Phase Deep Dive → Screenshots → Engineering Metrics → Security Architecture → DB Schema → Roadmap → Back Cover
Feature / Phase: Cover → Feature Summary → Implementation Details → Screenshots → Metrics → Next Steps
Sprint / Weekly: Header → Summary + Stats → Completed Items → Key Changes Table → Screenshots → Next Sprint
Step 5: Generate PDF
ALWAYS use agent-browser pdf. NEVER use weasyprint (has font rendering bugs causing invisible text).
agent-browser open "file:///absolute/path/to/docs/reports/report.html"
agent-browser pdf "/absolute/path/to/docs/reports/output.pdf"
agent-browser close
Step 6: Output Structure
docs/reports/
├── screenshots/ ← captured PNGs
├── report-YYYY-MM-DD.html ← HTML source (keep for regeneration)
└── {name}-report-YYYY-MM-DD.pdf ← final PDF
Naming: {project}-progress-report-{date}.pdf | {feature}-report-{date}.pdf | sprint-report-{date}.pdf
After PDF generation, offer to clean up screenshots/ if not needed. Always keep the HTML source.
Quality Checklist
