mikeonbreeze/cc-crossbeam/adu-plan-review

ADU Plan Review — City Corrections Generator

Overview

Review ADU construction plan submittals and generate a draft corrections letter. This is the city-side counterpart to the contractor-side adu-corrections-flow.

Same domain knowledge, opposite direction.

Sub-Skills

City Routing

The city knowledge source depends on whether the city has been onboarded:

Input: city_name
 
IF dedicated city skill exists (e.g., placentia-adu/):
  → Tier 3: Load city skill reference files (offline, fast, ~30 sec)
ELSE:
  → Tier 2: Run adu-city-research
    → Mode 1 (Discovery): WebSearch for city URLs (~30 sec)
    → Mode 2 (Extraction): WebFetch discovered URLs (~60-90 sec)
    → Mode 3 (Browser Fallback): Only if extraction has gaps (~2-3 min)

How to detect onboarded cities: Check for a city skill directory at skill/{city-slug}-adu/SKILL.md. If it exists, the city is onboarded. If not, fall back to web research.

Tier 1 (state law only) is always available — it's the california-adu skill. Even without any city knowledge, state law catches ~70% of common corrections.

Inputs

Review scope options:

• administrative — Cover sheet, sheet index, stamps/signatures, governing codes, project data. Fast (~2 min), HIGH confidence. Good for completeness screening.
• full — All sheet types, all check categories. Slower (~5-8 min), mixed confidence. Produces the draft corrections letter.

Outputs

All written to the session directory.

Workflow

Phase 1: Extract & Map

Run adu-targeted-page-viewer:

1. Check first: PNGs and title block crops may already be pre-extracted in project-files/pages-png/ and project-files/title-blocks/. If they exist, skip extraction and go straight to reading the cover sheet.
2. If PNGs don't exist: Extract PDF pages to PNGs: scripts/extract-pages.sh <binder.pdf> <output-dir>
3. Read cover sheet for sheet index
4. Match sheet IDs to pages (title block reading if needed)
5. Save sheet-manifest.json

~90 seconds (or ~30 seconds if PNGs are pre-extracted). Identical to Phase 2 of adu-corrections-flow.

Phase 2: Sheet-by-Sheet Review (FILE-BASED)

Review each sheet against the relevant checklist reference file. Group sheets by discipline to limit subagent count. Subagents write findings to files — they do NOT return findings to the orchestrator.

Subagent grouping:

Rolling window: 3 subagents in flight. arch-a + arch-b + site-civil start first. As each completes, launch the next.

Each subagent receives:

• The sheet PNG(s) for its assigned sheets (read from pages-png/)
• The relevant checklist reference file(s)
• The sheet manifest (for cross-reference context)
• Instructions to WRITE findings to its output file

Each subagent WRITES a findings JSON file containing an array — one entry per check:

• check_id — Which checklist item (e.g., "1A" = architect stamp)
• sheet_id — Which sheet (e.g., "A1")
• status — PASS | FAIL | UNCLEAR | NOT_APPLICABLE
• visual_confidence — HIGH | MEDIUM | LOW
• observation — What the subagent actually saw (evidence)
• code_ref — Code section this check is grounded in

Each subagent RETURNS only a short summary (e.g., "Done, wrote 12 findings to findings-arch-a.json"). The orchestrator collects this summary via TaskOutput but does NOT read the findings file.

Orchestrator verification: After all 5 subagents complete, use Glob to verify all 5 findings-*.json files exist. Do NOT read their contents.

~2-3 minutes for full review (5 subagents, 3-at-a-time rolling window).

Phase 3: Code Compliance (FILE-BASED, concurrent 3A + 3B)

After Phase 2 completes, launch two concurrent subagents to verify findings against code. Both subagents read findings from disk and write results to disk.

3A: State Law Verification

• Skill: california-adu
• Input: Read all findings-*.json files from the output directory. Focus on FAIL and UNCLEAR findings.
• Task: For each finding, look up the cited code section in the california-adu reference files. Verify: Is this actually required by state law? What are the exact thresholds? Are there ADU-specific exceptions?
• Output: Write output/state_compliance.json — per-finding code verification with exact citations
• Return: Short summary only (e.g., "Done, verified 18 findings against state law, wrote state_compliance.json")

Why this matters: The checklist reference files cite code sections, but the california-adu skill has the detailed rules with exceptions and thresholds. Phase 3A catches false positives — e.g., the checklist flags a 3-foot setback, but the ADU is a conversion and conversions have no setback requirement.

3B: City Rules

Route based on City Routing decision (see above).

If onboarded city (Tier 3):

• Read all findings-*.json files from the output directory
• Load city skill reference files
• Check findings against city-specific amendments, standard details, and IBs
• Fast — ~30 sec, all offline

If web research (Tier 2):

• Read all findings-*.json files from the output directory
• Run adu-city-research Mode 1 → Mode 2 → optional Mode 3
• Check findings against discovered city requirements
• Slower — ~90 sec to 3 min

Output: Write output/city_compliance.json — city-specific requirements, local amendments, standard details that apply to the findings Return: Short summary only

Orchestrator verification: After both subagents complete, use Glob to verify state_compliance.json and city_compliance.json exist. Do NOT read their contents.

Phase 4: Merge & Draft Corrections (FILE-BASED, dedicated subagent)

This is a dedicated subagent — the orchestrator does NOT merge findings itself. The Phase 4 subagent reads all artifact files from disk and produces the corrections letter.

Subagent reads from disk:

1. output/findings-*.json (5 files from Phase 2) — what the AI found on the plans
2. output/state_compliance.json (Phase 3A) — state law verification
3. output/city_compliance.json (Phase 3B) — city-specific rules
4. output/sheet-manifest.json (Phase 1) — for sheet references

For each finding, apply this filter:

Output format — `draft_corrections.json`:

Each correction item includes:

• item_number — Sequential
• section — Building, Fire/Life Safety, Site/Civil, Planning/Zoning
• description — The correction text (what needs to be fixed)
• code_citation — Specific code section(s)
• sheet_reference — Which sheet(s) are affected
• confidence — HIGH | MEDIUM | LOW
• visual_confidence — How certain the AI is about the visual observation
• reviewer_action — CONFIRM (quick check) | VERIFY (needs closer look) | COMPLETE (reviewer must fill in)

See references/output-schemas.md for full JSON schema.

Subagent writes 3 files:

• output/draft_corrections.json — structured corrections data
• output/draft_corrections.md — formatted markdown corrections letter (primary output for frontend + PDF conversion)
• output/review_summary.json — stats: items by confidence tier, review coverage, reviewer action items

Return: Short summary only (e.g., "Done, generated 14 corrections, wrote draft_corrections.json/md + review_summary.json")

PDF generation is handled externally — after this agent completes, the server converts draft_corrections.md to PDF outside the sandbox. Do NOT attempt PDF generation. Do NOT use adu-corrections-pdf. Do NOT install reportlab, puppeteer, or any PDF tools. Your job ends at draft_corrections.md.

Orchestrator verification: After Phase 4 subagent completes, verify draft_corrections.json, draft_corrections.md, and review_summary.json exist. Do NOT read their contents.

Timing

Reference Files

Checklist References (what to check per sheet type)