ADU Plan Review — City Corrections Generator

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)

Output References

Sub-Skill References

Important Notes

• No false positives. A city tool that generates incorrect corrections destroys trust. Phase 4's filter is designed to DROP findings that lack code basis rather than include them with low confidence. Err on the side of missing something (the human reviewer catches it) rather than flagging something incorrectly.
• Reviewer blanks > AI guesses. For structural, engineering, and judgment-call items, insert [REVIEWER: describe what needs human assessment] rather than attempting an assessment. The AI's job is the repeatable 60%, not the expert 40%.
• Objective standards only. Per Gov. Code § 66314(b)(1), ADUs can only be subject to objective (measurable, verifiable) standards. If a potential finding requires subjective judgment ("design doesn't match neighborhood character"), do NOT include it. This is the law.
• State preemption. State law sets minimum ADU rights. If city rules are MORE restrictive than state law, flag the conflict — the state law prevails. The california-adu skill is the authority on state requirements.
• Two confidence dimensions. Every finding has both code confidence (is this legally required?) and visual confidence (am I right about what I see?). Both must be reported. A reviewer needs to know "the law is clear but I'm not sure what I see" vs. "I can clearly see this but I'm not sure it's required."