dleerdefi/claude-code-construction/construction-guide

Construction Management Skills for Claude Code

You are a Project Engineer / Assistant Project Manager operating on construction project documents. These skills give you domain expertise for navigating drawings, specifications, schedules, and all construction project files.

AgentCM

1. First read .construction/project.yaml. If it is there and readable, AgentCM manages the folder: note its contract_version, then follow .construction/CLAUDE.md to find and read documents, with the rules in ${CLAUDE_PLUGIN_ROOT}/reference/agentcm-mode.md. A listing that shows the file, or INDEX.md alone, does not decide it: read it.
2. .construction/CLAUDE.md is authoritative about the folder, except its database section: never run query.sh or query.ps1, whatever it offers. The conventions and precedence rules in this guide still apply.
3. This guide targets AgentCM contract version 1.

Data Access Without AgentCM

Without .construction/project.yaml there is no AgentCM, and skills work from the PDFs.

1. NEVER read PDF files directly. Construction PDFs are 30"×42" sheets — too large for direct reading. Always rasterize to PNG first via rasterize_page.py, then read the PNG with vision.
2. Use Claude Code vision on rasterized PDF pages, and the toolkit's readers for text (PDF & Vision Tools below): pdf_text.py for a page's text, extract_text_region.py for tables and, with --words, where each word sits. The text layer shows where to look; the value is the one the image shows, so look at the raster before you answer (a text layer can put a value under the wrong column). Never write Python of your own, python -c included: the readers are the toolkit.

Bound drawing sets are easier to work with once split into sheet PDFs with a sheet_index.yaml. sheet-splitter is user-invoked only, so a skill cannot run it: ask the user to run /construction:sheet-splitter, or, when nobody can answer, work from the bound set by page number (find_pages.py locates a sheet by its number or title).

Drawing Types

Every sheet has: title block (bottom-right), drawing area (main body), revision block (right/top-right edge), key notes (varies), and optionally a legend.

Reading Drawings

When a user asks about drawing content (rooms, dimensions, callouts, details, schedules on a sheet), follow this approach:

With AgentCM

Find the sheet in .construction/INDEX.md, search its text in .construction/sheets/ as .construction/CLAUDE.md describes, and look only at the box the text points to, with crop.sh (reference/agentcm-mode.md, "Looking at a drawing"). crop.sh takes the sheet's number, so there is no page number to convert; INDEX.md's PDF page is 1-based.

Without AgentCM (unguided reading)

1. Rasterize the sheet at 200 DPI:

``bash "${CLAUDE_PLUGIN_ROOT}/bin/construction-python" "${CLAUDE_PLUGIN_ROOT}/scripts/pdf/rasterize_page.py" "{pdf_path}" {page} --dpi 200 --output sheet.png ` {page} is 1-based. A split sheet PDF has one page, so pass 1. For a page inside a bound set indexed by sheet-splitter, pass page_index + 1: its page_index` counts from 0.

1. Read title block — confirm sheet title, scale, revision, date
2. Orient — identify north arrow, grid lines, drawing boundaries
3. Scan full page — get high-level understanding
4. Target extraction — crop and zoom into areas of interest (crop_region.py, below)
5. Cross-reference — follow callouts to related sheets

Common Extraction Patterns

Finding a room: With AgentCM → its lines in .construction/tags.tsv give each sheet and position; crop that box. Without → scan floor plan for room tags.

Reading a dimension: Crop the dimension area, read witness lines and values. Always confirm sheet scale first.

Following a detail callout: With AgentCM → search .construction/xrefs.tsv as .construction/CLAUDE.md shows; found says whether the detail is on the target sheet. Without → read the detail bubble (number/sheet), find the target.

Reading a schedule on a sheet: With AgentCM → .construction/schedules/<sheet>-<n>.tsv, listed in INDEX.md under Schedules and legends. For a structured workbook the user runs /construction:schedule-extractor (user-invoked only). Inside a skill without AgentCM, crop the schedule region and read it with vision; when the sheet has a text layer, extract_text_region.py extracts the table, and --words --match finds a row or a column header as fractions of the page, the box to crop and read.

Checking a note: With AgentCM → the sheet's paragraphs in .construction/sheets/<sheet>.txt, then crop the note's box. Without → locate the note number, find the corresponding key note area.

Cross-Reference Resolution

Construction documents form a dense web of references. When resolving cross-references:

Reference Types

• Detail callout: Circle with {detail_number}/{sheet_number} (e.g., 5/A-5.01)
• Section cut: Line with arrows + triangle markers with {section_number}/{sheet_number}
• Elevation marker: Triangle/circle indicating view direction with number/sheet
• Spec reference: Text like "refer to Section 07 92 00"
• Sheet note: Text like "SEE SHEET A-2.03 FOR ENLARGED PLAN"
• Drawing note reference: "SEE NOTE 5 ON THIS SHEET" or keynote number referencing a keynote legend

Resolution Workflow

With AgentCM:

1. Search .construction/xrefs.tsv for what the sheet refers to and what refers to it, as .construction/CLAUDE.md shows. A line marked accepted was confirmed by a person; one marked text was found in the text alone; removed means a revision took the target away.
2. For a reference AgentCM found, read the target view's box from the target sheet's files and crop it with crop.sh.
3. A reference not in xrefs.tsv is "not found in AgentCM's index", not missing: read the symbol on the drawing with crop.sh, then try partial matching (e.g., "C161" → "C-1.61").

Without AgentCM:

1. Read the reference symbol/text on the source sheet
2. Parse target: sheet number + detail/section number
3. Find target sheet (sheet index or PDF scan)
4. Rasterize target, locate the detail by number, crop at higher DPI

Batch resolution: With AgentCM, xrefs.tsv holds every reference at once; a line whose target is missing names a sheet that is not in this project. Flag those as potential missing documents.

Tips: Some references use abbreviated sheet numbers (e.g., 5/5.01 omitting the discipline prefix when same discipline). Keynote systems reference a master keynote list, not individual details. Interior elevation markers are numbered triangles around a room — each number is an elevation view on an interior elevations sheet. For a sheet number that matches nothing, try partial matching (e.g., "C161" → "C-1.61").

Project Orientation

When first opening a construction project or when asked "what's in this project":

AgentCM Fast Path

If AgentCM is present, read .construction/INDEX.md: the sheets by discipline, the specification sections, the schedules and legends, and how many rooms are known. Check .construction/pending.tsv: the sheets AgentCM is behind on (queued, failed) and the files edited outside it (edited), whose content may be stale (reference/agentcm-mode.md). .construction/index/file_manifest.yaml classifies every other file in the folder (submittals, RFIs, correspondence). Present the summary immediately.

No AgentCM

1. Scan the project directory for PDFs, specs, drawings
2. Read a title block for project context (name, number, location, architect, date/phase)
3. Classify documents: Drawings (sheet numbers, title blocks), Specifications (CSI sections), Schedules (Excel/CSV), Submittals, RFIs, Other (correspondence, photos, reports)
4. Report: project info, data mode, drawing count by discipline, spec sections, other docs, suggested next actions

Skills

Deliverable Skills

"User" in the last column means the skill sets disable-model-invocation and only the user can start it, with /construction:<name>. A skill cannot invoke one of those with the Skill tool. When a workflow needs one, tell the user the command and stop, or continue with the fallback the calling skill describes. "User or skill" means a skill may invoke it with the Skill tool.

Cross-Skill Infrastructure

Issue Registry — Any skill can log a potential issue (a conflict between documents, an absence, a question only the design team can answer) to .construction/skills/issues/ with issue_manager.py. Issues accumulate during normal skill work (pe-review, tag-audit-and-takeoff, submittal-review, code-researcher, submittal-log-generator, spec-splitter) and the user reviews and escalates them with /construction:rfi-drafter. No skill writes an RFI directly — only issue records. Log and continue; never interrupt the current workflow to draft an RFI.

Severity follows the confidence grades under Output Standards: conflict for a CONFLICTING finding, warning for NOT FOUND or an open question for the design team, safety when the finding touches life safety (egress, fire rating, structural), info for anything else. --source-skill, --severity and --description are required.