demo-city-review
Skill297 starsChanged 9 months agoMITView on GitHub
Local demo: City-side ADU plan review. Point this at a plan binder (PDF or pre-extracted PNGs) and a city name. It reviews the plans sheet-by-sheet against state and city code, then generates a draft corrections letter. Fire-and-forget — no human-in-the-loop pause. Triggers on: 'Review this ADU plan set for [City]' or 'Run the city review on [path]'.
- Installs packages
In this repository15 other files it gives its agents.
- .claude/skills/crossbeam-ops/CLAUDE.mdCLAUDE.md
- adu-city-researchSkill
- adu-corrections-interpreterSkill
- cc-guideSkill
- crossbeam-opsSkill
- demo-contractor-correctionsSkill
- fal-aiSkill
- frontend-designSkill
- long-running-agentSkill
- nano-bananaSkill
- product-demo-videoSkill
- react-best-practicesSkill
- shadcnSkill
- skill-creatorSkill
- template-skillSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
21 rules. About 0 are common, 10 are distinctive, and 11 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈10
Distinctive · estimate
This author's own choices. Worth a look.
11
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Run a city-side ADU plan review locally.
- Distinctive: line 27
Use directly. Skip PDF extraction.
- Very specific: line 28
Check for pre-existing sheet-manifest.json in the same directory or parent.
- Very specific: line 29
Check for pre-existing title-blocks/ directory.
- Very specific: line 32
Check if pdftoppm is installed: which pdftoppm
- Very specific: line 33
If not: brew install poppler (macOS) or tell the user to install it
- Very specific: line 42
Create demo-output/city-review-<city>-<timestamp>/ in the workspace root.
- Very specific: line 48
Follow the adu-targeted-page-viewer skill workflow:
- Distinctive: line 50
Read page 1 (cover sheet) visually.
- Distinctive: line 51
If page count matches index count, map 1:1 in order.
- Distinctive: line 52
If mismatch, read title blocks to resolve (crop bottom-right 20% of each page, or use pre-cropped title blocks if available).
- Very specific: line 53
Write sheet-manifest.json to the output directory.
- Very specific: line 81
Write all findings to sheet_findings.json.
- Distinctive: line 90
Check for ADU-specific exceptions (Gov.
- Very specific: line 94
Check if adu-skill-development/skill/<city-slug>-adu/ exists
- Very specific: line 96
If no: Run the adu-city-research skill — Discovery (WebSearch) then Extraction (WebFetch)
- Distinctive: line 97
Check findings against city-specific amendments, standard details, IBs
- Distinctive: line 107
No code basis found → drop it (no false positives)
- Very specific: line 115
Write review_summary.json — stats on items found, confidence breakdown, coverage
- Distinctive: line 119
After all phases complete, present to the user:
- Distinctive: line 130
State preemption: If a city rule is more restrictive than state law, flag the conflict — state law prevails.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Demo: City Plan Review
Run a city-side ADU plan review locally. You are a city plan checker reviewing an ADU permit submittal for code compliance.
How to Invoke
The user provides:
- Plan binder — either a PDF path or a directory of pre-extracted PNGs
- City name — e.g., "Placentia", "Buena Park", "Long Beach"
- (Optional) Project address
Example invocations:
- "Review this ADU plan set for Placentia:
test-assets/city-flow/mock-session/pages-png/" - "Run city review on
test-assets/01-extract-test/pages-png/for Buena Park" - "Review
path/to/plans.pdffor the City of Long Beach"
Input Resolution
Determine what the user gave you:
If a directory of PNGs (e.g., pages-png/page-01.png, page-02.png, ...):
- Use directly. Skip PDF extraction.
- Check for pre-existing
sheet-manifest.jsonin the same directory or parent. If found, load it and skip manifest building. - Check for pre-existing
title-blocks/directory. If found, use those for manifest building.
If a PDF file:
- Check if
pdftoppmis installed:which pdftoppm - If not:
brew install poppler(macOS) or tell the user to install it - Extract pages: create a
pages-png/directory next to the PDF and run:pdftoppm -png -r 200 "<input.pdf>" "<output-dir>/pages-png/page" - Rename outputs to
page-01.png,page-02.png, etc. (pdftoppm outputspage-01.pngformat already with the prefix)
Output Directory
Create demo-output/city-review-<city>-<timestamp>/ in the workspace root. All output files go here.
Workflow
Phase 1: Sheet Manifest (~30-90 sec)
Follow the adu-targeted-page-viewer skill workflow:
- Read page 1 (cover sheet) visually. Extract the sheet index.
- If page count matches index count, map 1:1 in order.
- If mismatch, read title blocks to resolve (crop bottom-right 20% of each page, or use pre-cropped title blocks if available).
- Write
sheet-manifest.jsonto the output directory.
Phase 2: Sheet-by-Sheet Review (~3-5 min)
Review sheets in parallel using subagents. Group by discipline:
Subagent A — Administrative + Architectural:
- Cover sheet (CS): stamps, signatures, governing codes list, sheet index accuracy, project data
- Floor plan (A-series): room dimensions, fixture counts, egress, accessibility
Subagent B — Site + Civil:
- Site plan: setbacks, lot coverage, FAR, parking, utility connections shown, easements
- Grading/drainage: slopes shown, drainage direction, "For Reference Only" stamp
Subagent C — Elevations + Fire/Life Safety:
- Elevations: height compliance, fire separation distance (< 5' from property line = 1-hour rated), roof plan consistency
- Building sections: insulation, foundation-to-wall connection
Launch all three concurrently. Each subagent reads the relevant PNGs and produces findings.
For each finding, record:
check: What was checkedstatus: PASS | FAIL | UNCLEAR | NOT_APPLICABLEconfidence: HIGH | MEDIUM | LOWobservation: What was actually seen on the plancode_ref: Code section (CRC, CBC, Gov. Code, municipal code)sheet_idandpage_number
Write all findings to sheet_findings.json.
Phase 3: Code Verification (concurrent, ~60-90 sec)
Launch two parallel subagents:
3A — State Law Verification:
- Load reference files from
adu-skill-development/skill/california-adu/references/ - For each FAIL and UNCLEAR finding, verify the code citation
- Check for ADU-specific exceptions (Gov. Code § 66310-66342)
- Write
state_compliance.json
3B — City Rules:
- Check if
adu-skill-development/skill/<city-slug>-adu/exists- If yes (onboarded city): Load the city skill reference files. Fast, offline.
- If no: Run the
adu-city-researchskill — Discovery (WebSearch) then Extraction (WebFetch)
- Check findings against city-specific amendments, standard details, IBs
- Write
city_compliance.json
Phase 4: Draft Corrections Letter (~2 min)
Merge all inputs and generate the corrections letter:
- For each finding, apply the filter:
- Confirmed by code → include with citation
- Confirmed but LOW visual confidence → include with
[VERIFY]flag - No code basis found → drop it (no false positives)
- Structural/engineering adequacy →
[REVIEWER: ...]blank for human - Subjective judgment → drop it (prohibited for ADUs per Gov. Code § 66314(b)(1))
- Write two outputs:
draft_corrections.json— structured, each item with code citation, confidence, reviewer_actiondraft_corrections.md— formatted markdown corrections letter ready to read
- Write
review_summary.json— stats on items found, confidence breakdown, coverage
Phase 5: Present Results
After all phases complete, present to the user:
- Summary: how many items found, confidence breakdown
- The full
draft_corrections.mdcontent - Note which items need
[VERIFY]or[REVIEWER]attention - List output files written
Key Rules
- No false positives. Drop findings without code basis. It's better to miss something than to flag something incorrectly.
- Reviewer blanks > AI guesses. For structural and engineering items, use
[REVIEWER: ...]instead of guessing. - Objective standards only. ADUs can only be subject to objective, measurable standards (Gov. Code § 66314(b)(1)). Never flag subjective design issues.
- State preemption. If a city rule is more restrictive than state law, flag the conflict — state law prevails.
- Two confidence dimensions. Report both code confidence (is this legally required?) and visual confidence (am I correct about what I see?).
Test Data
Ready-to-use test data for demos:
| Test Set | City | Path |
| 1232 N Jefferson | Placentia | test-assets/city-flow/mock-session/pages-png/ (15 pages, title blocks in ../title-blocks/) |
| Same project | Placentia | test-assets/01-extract-test/pages-png/ (15 pages, same project) |
Pre-built mock session data (for comparison): test-assets/city-flow/mock-session/sheet-manifest.json
Sub-Skills Referenced
| Skill | Location | Role |
adu-targeted-page-viewer | adu-skill-development/skill/adu-targeted-page-viewer/ | PDF extraction + sheet manifest |
california-adu | adu-skill-development/skill/california-adu/ | State law (28 reference files) |
adu-city-research | .claude/skills/adu-city-research/ | Web research for non-onboarded cities |
placentia-adu | adu-skill-development/skill/placentia-adu/ | Placentia-specific rules (onboarded) |
buena-park-adu | adu-skill-development/skill/buena-park-adu/ | Buena Park-specific rules (onboarded) |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

