Progress Report Generator

Generate professional PDF progress reports with live screenshots, metrics, and charts.

Workflow

1. Determine report scope (full project / feature / sprint)
2. Gather metrics from the codebase
3. Capture dashboard screenshots via agent-browser
4. Build the HTML report from the template
5. Generate PDF via agent-browser pdf
6. 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 "admin@example.com"
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 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 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

• All text renders in the PDF (no invisible text)
• Screenshots load (no broken images)
• Page breaks don't split cards/tables/screenshots
• Stat numbers verified against actual codebase
• Date, author, version are correct
• No placeholder text remains