mikeonbreeze/cc-crossbeam/adu-corrections-pdf

ADU Corrections PDF Generator

Overview

Take a draft corrections letter in markdown and produce a professional PDF. This is a formatting-only sub-agent invoked by the research agent at the end of the pipeline.

Depends on: document-skills/pdf — the primitive PDF skill. Load it for the actual PDF generation tools (reportlab for Python, pdf-lib for JavaScript). This skill adds the domain-specific formatting on top.

What This Skill Does and Does NOT Do

Inputs

Outputs

Workflow

Step 1: Read Draft Markdown

Read the .md file. Validate expected structure: header block, notice, numbered sections, summary tables. Log warnings on unexpected structure but don't fail.

If fix_instructions are provided (re-invocation after failed QA), apply them before generating. Fix instructions might say: "Header is cut off — add more top margin" or "Table overflows page — reduce font size."

Step 2: Generate PDF

Use the `document-skills/pdf` primitive skill for the actual PDF generation. Two recommended approaches:

Approach A: reportlab (Python — best for structured layouts)

Use reportlab.platypus (SimpleDocTemplate, Paragraph, Table, Spacer, PageBreak) to build the letter programmatically. See document-skills/pdf/SKILL.md for reportlab patterns. This gives the most control over pagination, headers/footers, and table formatting.

Key reportlab elements for this letter:

• SimpleDocTemplate with letter pagesize and margins
• Paragraph with custom styles for section headers, item titles, body text, code citations
• Table + TableStyle for the review summary and sheet manifest tables
• Custom PageTemplate for the city letterhead header and draft footer on every page

Approach B: markdown → HTML → PDF (faster to implement)

1. Convert markdown to HTML (use marked npm or Python markdown library)
2. Inject into HTML template with references/letter-styles.css
3. Render to PDF using puppeteer, md-to-pdf, or wkhtmltopdf

See document-skills/pdf/reference.md for pypdfium2 rendering and pdf-lib JavaScript options.

Step 3: Screenshot for QA

Convert page 1 of the generated PDF to a PNG. Use document-skills/pdf tools:

# Using pypdfium2 (from document-skills/pdf/reference.md)
import pypdfium2 as pdfium
pdf = pdfium.PdfDocument("corrections_letter.pdf")
bitmap = pdf[0].render(scale=2.0)
img = bitmap.to_pil()
img.save("qa_screenshot.png")

Or command line:

pdftoppm -png -r 200 -f 1 -l 1 corrections_letter.pdf qa_screenshot

Return the screenshot path to the calling agent. The calling agent handles the QA decision — this skill just provides the screenshot.

Letter Format Spec

Page Layout

• Size: US Letter (8.5" x 11")
• Margins: 1" top/bottom, 0.75" left/right
• Font: Arial/Helvetica — 10pt body, 12pt section headers, 14pt city name
• Line spacing: 1.3

Header (every page)

CITY OF [CITY NAME]
BUILDING AND SAFETY DIVISION
PLAN CHECK CORRECTIONS — AI-ASSISTED DRAFT

AI Notice Banner (page 1 only)

Light yellow box with amber border:

NOTICE: This is an AI-generated DRAFT corrections letter. Items flagged [VERIFY] require closer inspection. Items flagged [REVIEWER] require licensed professional assessment. A human plan checker must review and approve before issuance.

Confidence Badges (inline, color-coded)

• CONFIRM → green (quick check, HIGH confidence)
• VERIFY → amber (needs closer look, MEDIUM confidence)
• REVIEWER → red (requires licensed professional)
• COMPLETE → gray (human must fill in entirely)

Footer (every page)

Page [N] of [M]
AI-Assisted Draft — Not For Issuance Without Review
CrossBeam ADU Plan Review | [Timestamp]

Section Order

1. Planning / Zoning
2. Building
3. Site / Civil
4. Fire / Life Safety
5. Structural [REVIEWER]
6. Process Notes (Informational)
7. Review Summary (tables)

Dependencies

References

Important Notes

• Never modify correction content. Format exactly as received. Content issues are the research agent's problem.
• Every page must say DRAFT. Header, footer, and notice banner. This document cannot be mistaken for an official city issuance.
• Fail gracefully. If styling breaks, produce a plain-formatted PDF anyway. A plain PDF beats no PDF.
• Accept fix instructions. When re-invoked after a failed QA, the main agent will provide specific fix instructions. Apply them and regenerate.