Count-based QTO for tagged construction elements — fixtures, devices,\ndoors, equipment, and any element identified by a tag/symbol on drawings.\nDoes NOT do area (sqft) or linear (lf) takeoffs — only discrete counts.
\nThe QTO is a byproduct of the audit. The real value: the completeness\nengine that finds what's tagged, what's missing, and produces a defensible\ncount with full provenance for every number.
\nDoes NOT: do area/linear takeoffs, create outbound documents autonomously,\noverride user-approved groupings, or assume quantities without provenance.
\nRead .construction/project.yaml at the project root: present and readable means AgentCM mode (note its contract_version), absent means flat-file mode. A listing that shows the file does not decide it: read it.
AgentCM mode (.construction/project.yaml exists):
${CLAUDE_PLUGIN_ROOT}/reference/agentcm-mode.md: which source wins, what a missing file or an empty search means, sheet ids, and how to record a correction of AgentCM's data (a missed tag goes through the ingest in Step 8).construction/CLAUDE.md for project context and where things are,\nexcept its database section: never run query.sh or query.ps1, whatever\nthe guide offers.construction/database.yaml for project_id and api_url, nothing else in it{sheet_id} in Step 8's payload is\nthe id of the entry in .construction/index/sheet_index.yaml whose\nsheet_number is that sheet. Never guess it from the number. If that file is\nmissing, or its entries have no id (an older sheet-splitter wrote a pages:\nlist with filename and page_index), say so and stop.sh .construction/crop.sh <sheet> <x> <y> <w> <h> (or\npowershell -File .construction/crop.ps1 <sheet> <x> <y> <w> <h>) renders\nthat box of the sheet's PDF page as a PNG and prints its path. <sheet> is\nthe sheet's number as .construction/INDEX.md names it; the box is 0 to 1\nfrom the top left of the sheet. Never rasterize whole sheets, and never ask\nfor rasters/ or graph/export: they are not part of AgentCM's contract..construction/sheets/<sheet>.tsv (Steps 3-4)POST {api_url}/projects/{project_id}/tag-detections/ingest, sent from the outbox (Step 8)Flat File mode (no .construction/project.yaml):
\"${CLAUDE_PLUGIN_ROOT}/bin/construction-python\" \"${CLAUDE_PLUGIN_ROOT}/scripts/pdf/rasterize_page.py\" \"<pdf>\" <page> --dpi 200 --output \".construction/skills/tag-audit-and-takeoff/pages/<sheet>.png\"\n(working data: never /tmp or any other folder outside the project).construction/skills/tag-audit-and-takeoff/qto/ (Step 8)User provides: (1) tag type — e.g., \"plumbing fixtures\", \"doors\",\n\"light fixtures\" (see references/tag-types.md for full list), and\n(2) sheet scope — specific sheets, a discipline, or \"all sheets\".\nConfirm scope before proceeding.
REQUIRED: Tag type resolution (AgentCM mode). The tag_type sent to\nAgentCM is one of contract 1's canonical names, listed in\n${CLAUDE_PLUGIN_ROOT}/reference/agentcm-mode.md (Tag types), and nothing\nelse. Never invent one, and never send the takeoff's grouping as a type:
room_tag; door tags → door_tagdetail_callout, section_callout, callout_single_ref) →\nsimple_callout; multi-reference callouts (elevation markers with N/E/S/W\nspokes; multi_callout, callout_multi_ref) → multi_detail_calloutelement_tagReport to the user: \"Resolved type: '' (from '')\" and get\nconfirmation. If the request fits none of these, or two, ask the user.
\nThe takeoff's grouping comes from the files (AgentCM mode). Plumbing\nfixtures, light fixtures and equipment are groups of the report, never types:\na tag's code (WC-1, L2) belongs to the schedule whose key column holds it,\n.construction/schedules/<sheet>-<n>.tsv (INDEX.md's Schedules and legends\ntable names each), and .construction/tags.tsv gives its kind (the lines\nstarting with the code and a tab). Each line item's group is that schedule,\nnamed as INDEX.md names it, with its sheet; a code found in no schedule is\ngrouped as not in any schedule and listed (references/qto-output-format.md).\nA takeoff of an element_tag group counts the codes of its schedule.
HARD GATE — you MUST complete this step before proceeding to Step 2.\nDo not skip this step.
\nBefore scanning sheets, read what's already tagged per sheet, from AgentCM's\nfiles (never its API; the same whether AgentCM is open or closed):
\n.construction/sheets/<sheet>.groups.tsv whose\ntype is the resolved type (box x y w h, text), and the lines of\n.construction/tags.tsv for that sheet with accepted in how and the\nkind of that tag (room for room_tag, door for door_tag; for element_tag,\nthe codes in the takeoff's scope). A tags.tsv line is a point (x y): one\ninside a .groups.tsv box of the type is that group, the same tag, whatever\nits text's word order (\"101 OFFICE\" there is \"OFFICE 101\" in .groups.tsv).\nOne inside no such box gets the box Step 8 gives a tag: around its own lines\nin the sheet's .tsv (the lines its text is made of, at that point).construction/sheets/<sheet>.tsv with the\nresolved type in tag and pending in how, grouped into tags as Step 5\ngroups (\"STORAGE\" over \"202\" is one tag).construction/skills/tag-audit-and-takeoff/outbox/ (an earlier run's, saved\nwhile AgentCM was closed): not yet in AgentCM.construction/pending.tsv lists, when it exists\n(read its columns by their header names; sheet names the sheet): their\nfiles are behind or were edited outside AgentCM. Every tag on such a sheet is\nto confirm, reason \"this sheet's file is behind or edited\", never\nconfirmed, even when its file says acceptedReport to user: \"Sheet A-1.4: 12 tags already detected (8 accepted, 4 pending, 0 waiting).\"
\nReconciliation rules (the count, references/qto-output-format.md):
pending.tsv doesn't list..tsv has no text for (Step 8): no card, so nothing to accept.detection_id, and drop this run's sighting of it.already_held with that card, never as a second card (Step 8)Run it twice, get the same numbers. A second run matches its sightings to\nthe first run's tags: pending in AgentCM's files once they are refreshed,\nwaiting in the outbox, or, while the files have not caught up, through\nAgentCM's answer: a tag sent again comes back already_held with the first\nrun's card and counts once. The same confirmed, to confirm and possible total.
Before proceeding to Step 2, report coverage and get confirmation:\n\"Existing coverage: sheets have accepted, pending detections\nfor this tag type. sheets have zero coverage.\nProceed with the vision scan of the sheets in scope?\"\nEvery sheet in scope is looked at, covered or not: existing tags are matched,\nnever skipped (one tag, once), and coverage only narrows the neighborhood\nsearch within a sheet (the EXCLUDE rule above), never which sheets are scanned.\nWait for explicit user confirmation before continuing.
\nCRITICAL — Vision is MANDATORY for this step.
\nExamine each sheet image. Identify all visible tags of the requested\ntype. Return tag texts and view type classification — no coordinates.
\nIn AgentCM mode a sheet is read in boxes through crop.sh (Step 0): one\nbox per view, from the ## view headings in .construction/sheets/<sheet>.txt\n(each heading gives the view's area as x, y, w, h), or quadrants\n(0 0 0.5 0.5, 0.5 0 0.5 0.5, 0 0.5 0.5 0.5, 0.5 0.5 0.5 0.5) for a\nsheet without views. If crop.sh refuses a box as too large to read (exit 2),\nsplit it in four and crop those. Keep each PNG with its box: a point at pixel\n(px, py) in a crop of box (x, y, w, h) sized W × H pixels is at sheet position\n(x + px / W × w, y + py / H × h).
The views or quadrants cover the whole sheet. Never crop only around the tags\nthe sheet's text names: a tag drawn as linework, with no text layer, has no\nline in the sheet files, and only these boxes show it. It is a seen tag\n(Step 8). In the 2026-10-14 runs, crops around the text-known room tags\nmissed STAIR 107, drawn as outlines at the sheet's right edge.
\nVision must classify each tag's view: FLOOR PLAN, ENLARGED PLAN,\nDETAIL, SECTION, or ELEVATION. This determines record type in Step 5.\nClassification signals are in references/tag-types.md.
In Flat File mode: This is the primary (and only) identification step.\nProvide rough locations (\"upper-left quadrant\") for markup purposes.
\nFor each vision-identified tag, find its spatial anchor in the sheet's\n.construction/sheets/<sheet>.tsv (one line of text per row: x y w h source tag how label para view zone text, the text last) using the most\ndistinctive word in the tag text. \"WALK-IN FREEZER\" → search \"FREEZER\".\n\"WOMEN'S RESTROOM\" → search \"WOMEN\".
grep -i \"FREEZER\" \".construction/sheets/<sheet>.tsv\"\nMultiple hits expected — each is a potential tag location. Zero hits\n→ try alternate words. Still zero → flag \"vision-only, no OCR anchor\".
\nFor each anchor, pull the sheet's nearby lines: those whose x and y fall\nwithin the padding of the anchor's. Padding values by tag type in\nreferences/spatial-params.md. Target: 8-25 candidates per tag.
awk -F'\\t' 'NR > 1 && $1 >= {anchor_x - pad} && $1 <= {anchor_x + pad} && $2 >= {anchor_y - pad} && $2 <= {anchor_y + pad}' \".construction/sheets/<sheet>.tsv\"\nAdaptive: double padding if < 3 items returned, reduce 30% if > 40.
\nGive Claude the vision tag text and the small candidate set (~15-20\nitems). Group constituent items following references/grouping-rules.md\n— text reconstruction, spatial coherence, include/exclude criteria,\nconfidence scoring.
Batching: Process ALL tags per sheet in one call. 12 tags × ~200\ntokens each = ~2400 tokens. Never load the sheet's whole .tsv.
Flat File mode: Skip grouping. Tags come from vision only. Mark\nall detections as confidence: \"vision_only\" in output.
Validation checkpoint (after first 3 sheets):\nAfter grouping tags on the first 3 sheets, STOP and present 5 sample\ngrouped detections to the user. Show for each:
\nGet explicit user confirmation: \"Grouping quality acceptable? Proceed\nwith remaining sheets?\" Do not continue until confirmed.
\nREQUIRED for all modes. Mark up each sheet with visual highlights\nso the user can see exactly what was identified.
\nQTO markup must show ALL tagged items per sheet — not just newly detected.\nTake the existing tags from Step 1.5 (accepted, pending and waiting, read from\nthe files) and include them in the markup alongside new detections. Use color to distinguish:
\n--color \"green\" for accepted items (from previous detection/review)--color \"blue\" for newly detected items (this session)--color \"orange\" for pending review itemsRun the markup script once per color group per sheet, layering onto the same\noutput image (use the previous output as --base for the next pass).
# Build items JSON with one entry per detected tag\n# Then call the shared markup script:\n\"${CLAUDE_PLUGIN_ROOT}/bin/construction-python\" \\\n \"${CLAUDE_SKILL_DIR}/scripts/markup_tags.py\" \\\n --base \"{sheet_image_path}\" \\\n --items \"{items_json_path}\" \\\n --output \"{output_path}\" \\\n --color \"blue\" \\\n --label-style \"numbered\"\nItems JSON format (pixel coordinates):
\n[\n {\"x\": 2500, \"y\": 1800, \"shape\": \"circle\", \"radius\": 20, \"label\": \"WALK-IN FREEZER\"},\n {\"x\": 3100, \"y\": 2200, \"shape\": \"circle\", \"radius\": 20, \"label\": \"DRY STORAGE\"}\n]\nConvert normalized 0-1 coordinates to pixels using sheet image dimensions.
\nIn AgentCM mode the base images are the crop.sh PNGs from Step 2, one\nmarked-up image per box: give --base the crop's path and the items' pixel\npositions within that crop (sheet position minus the box's x and y, divided by\nits w and h, times the image's width and height). The crops live in AgentCM's\n.construction/crops/; write the marked-up PNGs to the project directory.
If PDF is available, also create native PDF annotations:
\n\"${CLAUDE_PLUGIN_ROOT}/bin/construction-python\" \\\n \"${CLAUDE_PLUGIN_ROOT}/scripts/pdf/annotate_pdf.py\" \\\n --pdf \"{pdf_path}\" --items \"{items_json}\" --output \"{output_pdf}\" \\\n --author \"Claude Code QTO\"\nRecord type depends on view type. Full data model in\nreferences/quantity-model.md.
Floor plan tags → Element Instance. One tag = one installed item.\nDetail/section/elevation tags → Element Type Definition. Template.
\nPre-ingest confirmation (REQUIRED before POSTing):\nBefore making ANY ingest API calls, present this summary to the user:
\n\"Ready to ingest new detections as ''? (Y/N)\"
\nDo NOT POST to the ingest endpoint until the user explicitly confirms.\nIngesting without confirmation is a blocking violation of this skill.\nThe server enforces a maximum of 100 detections per request — batch\nyour ingest calls per sheet.
\nWrite the payloads and the QTO JSON with the Write tool, never with a script,\npython -, a heredoc or a file in /tmp: qto_to_xlsx.py checks the QTO\nJSON, and AgentCM checks each detection.
AgentCM mode: write each sheet's payload, {\"sheet_id\": \"{sheet_id}\", \"detections\": [...]},\nto .construction/skills/tag-audit-and-takeoff/outbox/tag-detections-ingest-<sheet>-<YYYYMMDD-HHMMSS>.json\nand send it as ${CLAUDE_PLUGIN_ROOT}/reference/agentcm-mode.md says under\nWriting back; if AgentCM is closed, the payload waits there and the PE is told:
curl -sS -X POST \"{api_url}/projects/{project_id}/tag-detections/ingest\" \\\n -H \"Content-Type: application/json\" \\\n -d @\".construction/skills/tag-audit-and-takeoff/outbox/tag-detections-ingest-<sheet>-<YYYYMMDD-HHMMSS>.json\" \\\n -w \"\\nHTTP %{http_code}\\n\"\nEach detection: { bounding_box, tag_text, tag_type, confidence, view_type, room_id }.
bounding_box: { x, y, width, height }, 0 to 1 from the sheet's top left:\nthe box around the tag's own lines in the sheet's .tsv (Steps 4-5), from\ntheir smallest x and y to their largest x + w and y + h. AgentCM\ntakes the texts whose centres fall inside it and that no card holds.tag_type: the canonical name resolved in Step 1. view_type and room_id\nwhen known. Leave element_ids out: AgentCM goes by the box..tsv (vision only, Step 3) is not sent:\nthere is no text for a card to hold. It is seen on the drawing, not in\nAgentCM (below), ingest not_sent.Read AgentCM's answer, every detection; never assume success. HTTP 200\nmeans the request was well formed, not that each tag was taken. results[]\nholds one entry per detection, in order (index is its place in\ndetections), each with one outcome:
created: a new pending card, suggestion_id. To confirm; the instance's\ndetection_id is that id, ingest created.already_held: a card already holds those texts, held_by\n{suggestion_id, status}. The tag is that card, counted once:\ndetection_id its id, status accepted when the card is accepted, else\nto_confirm; ingest already_held. Never a second instance of it.rejected: the PE already turned this tag down in AgentCM\n(rejected_by.suggestion_id). Off the to-confirm list and out of the count:\nstatus rejected, detection_id that card's id, ingest rejected. The\nexport lists it once under \"Rejected in AgentCM\"; never report it again, as\nfound, missed or to confirm.no_free_text: no text's centre is inside the box, so the box was wrong.\nLook at the sheet's .tsv around the crop: if the tag's text has lines\nthere, redraw the box around them and send that detection once more; its\nanswer is the outcome. No text at all in that area: the tag is seen on the\ndrawing, not in AgentCM (below), ingest no_free_text.new_type: true on any entry: a type outside contract 1's list was sent,\na bug in this skill. Say so: name the type, and tell the PE a new tag kind\nwas created in AgentCM by mistake.outbox/.Seen on the drawing, not in AgentCM (the drawing shows the tag; AgentCM\nhas no text for it): status seen, bounding_box estimated from the crop,\ncrop the PNG crop.sh printed. Not to confirm: no card exists, so nobody\ncan accept it in AgentCM; it is in the possible total. Report it once in\ncorrections.tsv, which says nothing when the same tag is already there:
\"${CLAUDE_PLUGIN_ROOT}/bin/construction-python\" \"${CLAUDE_PLUGIN_ROOT}/scripts/corrections_append.py\" --once \\\n --sheet <sheet> --x <x> --y <y> --w <w> --h <h> --kind tag --crop \"<crop>\" --agentcm \"\" --drawing \"<tag text>\"\ncorrections is appended, or reported earlier, line N when it prints\nREPORTED EARLIER. To clear one, the PE draws its text on AgentCM's canvas and\ntags it; the next run finds it pending or accepted.
Report each sheet's outcomes: \"A-101: 3 sent: 2 created, 1 already held (pending); 1 seen, not in AgentCM.\"\nResults appear as highlighted overlays in AgentCM's canvas UI.
\nIn both modes, once the QTO JSON is saved (below), record a finding in .construction/skills/tag-audit-and-takeoff/findings/:
\"${CLAUDE_PLUGIN_ROOT}/bin/construction-python\" \"${CLAUDE_PLUGIN_ROOT}/scripts/graph/write_finding.py\" \\\n --skill \"tag-audit-and-takeoff\" --type \"qto_{tag_type}\" \\\n --title \"QTO: {tag_type_display} — {confirmed} confirmed, {possible} possible across {N} sheets\" \\\n --output-file \"{qto_json_path}\" \\\n --data '{\"tag_type\": \"...\", \"confirmed\": ..., \"to_confirm\": ..., \"seen_not_in_agentcm\": ..., \"possible_total\": ..., \"sheets\": [...], \"ingested\": ...}'\nCRITICAL — use the EXACT schema from references/qto-output-format.md.\nThe Excel script is rigid and parses specific key names. Required keys:
line_items[] (NOT qto_lines) — one entry per unique element/designationinstance_details[] with detection_id, sheet, tag_text, room, bounding_box, status (accepted, to_confirm, seen or rejected), source, confidence; reason on a tag of a sheet that is behind; crop and corrections on a seen tagscope{} with mode (agentcm or flat_file), completeness{}, issues[]What the count holds (Step 1.5): every tag once, in one of four groups.\naccepted instances are the confirmed count; a tag with a card not yet\naccepted, waiting in the outbox or on a sheet that is behind is to_confirm,\nwith its source (pending_in_agentcm, waiting_in_outbox, or\nfound_this_run with ingest created, already_held or outbox); a tag\nAgentCM has no text for is seen; a tag the PE rejected is rejected, in no\nnumber; derived instances are to confirm too. In flat-file mode nothing is\naccepted: every tag is to_confirm. The export computes the numbers per item\n(confirmed, to confirm, seen not in AgentCM, possible total), prints them, and\nrefuses a file that lists the same tag twice or a seen tag without its crop.\nReport the export's lines, never your own tally, and the caveat in its words.
Both modes: Save the QTO JSON (working data) to\n.construction/skills/tag-audit-and-takeoff/qto/{tag_type}_{timestamp}.json and the\nmarked-up PNGs (deliverables) to the project directory.
Excel export (both modes): Pass that QTO JSON as {qto_json_path}\nand invoke the export script to produce a styled multi-sheet workbook:
\"${CLAUDE_PLUGIN_ROOT}/bin/construction-python\" \\\n \"${CLAUDE_SKILL_DIR}/scripts/qto_to_xlsx.py\" \\\n --data \"{qto_json_path}\" \\\n --project \"{project_name}\" \\\n --scope \"{tag_type_display}\" \\\n --output \"QTO_{tag_type}_{date}.xlsx\"\nThe workbook has 6 sheets: QTO Summary (confirmed, to confirm and possible\ntotal per line item, with the caveat), Instance Detail (every detection with\nprovenance), Type Definitions (templates applied to rooms), Completeness\n(coverage metrics), To Confirm in AgentCM (every tag not yet accepted), and\nRejected in AgentCM (tags the PE already turned down there, in no number).
\nAfter type definitions are identified from details/sections/enlarged\nplans, resolve where they apply. Full logic: references/quantity-model.md.
Three methods (in order of reliability):
\nDeduplication: direct instances always take precedence over derived.
\nCompare detected counts against schedules (door, fixture, equipment)\nwhen available. Report: \"[tag type]: X detected, Y expected, Z%\ncoverage. Gaps on sheets: [list].\" No schedule → report raw counts.
\nAllowed scripts — exhaustive list. Only execute these scripts during this skill:
\n${CLAUDE_PLUGIN_ROOT}/scripts/pdf/rasterize_page.py — rasterize a sheet PDF page to PNG (flat file mode).construction/crop.sh / crop.ps1 (a box of a sheet as a PNG), in AgentCM modescripts/markup_tags.py — sheet markup with tag highlights${CLAUDE_PLUGIN_ROOT}/scripts/pdf/annotate_pdf.py — native PDF annotationsscripts/qto_to_xlsx.py — QTO Excel export (6-sheet workbook; computes and prints confirmed, to confirm and possible total, and lists rejected tags apart; refuses a tag listed twice)${CLAUDE_PLUGIN_ROOT}/scripts/issue_manager.py — log schedule/drawing count mismatches to the Issue Registry (command and severity mapping in construction-guide)${CLAUDE_PLUGIN_ROOT}/scripts/graph/write_finding.py — record the QTO as a finding (Step 8)${CLAUDE_PLUGIN_ROOT}/scripts/corrections_append.py — AgentCM mode: record a correction of AgentCM's data other than a missed tag (reference/agentcm-mode.md), and, with --once, a tag seen on the drawing that AgentCM has no text for (Step 8)