dleerdefi/claude-code-construction/subcontract-writer

Subcontract Writer

Generates a complete, execution-ready subcontract agreement from a firm's template, the awarded bid, and project specifications. You are the intelligence layer — you read every document, extract all data, generate every article's text, make legal/commercial judgments, and write fully-populated JSON files. The Python formatter is a thin rendering utility that makes no content decisions.

Output: Word document (.docx) matching the firm's template structure.

Dependency: Requires python-docx in the construction Python environment.

Key principle: The bid document is the PRIMARY input. It establishes what was priced, at what rates, with what inclusions and exclusions. Specifications inform scope descriptions and technical requirements. The template provides article structure and standard boilerplate.

Pipeline Position

This skill can be invoked directly when the user has an awarded bid and wants to generate a subcontract, or as the final step of the bid pipeline:

/bid-tabulator → /bid-evaluator → user confirms → THIS SKILL

Either way, the awarded bid document (Slot B) is the mandatory input.

Mode Detection

Read .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: Read each spec section from .construction/specs/<section>.txt (09 65 13 is 09-65-13.txt; each line starts with its page), listed in .construction/INDEX.md: it is the section's text, and a section's pages are never extracted again from the PDF. A read manual's pages in no section (INDEX.md lists them) are read in the PDF, those pages only. Only for a manual INDEX.md lists under "Spec manuals not read", read spec-splitter's .construction/skills/spec_text/ instead. Use sheet index from .construction/index/sheet_index.yaml for drawing references. Read project metadata from .construction/CLAUDE.md. Follow ${CLAUDE_PLUGIN_ROOT}/reference/agentcm-mode.md (which source wins, missing files).
• Flat File mode: Discover spec PDFs via project CLAUDE.md paths or directory search. Read drawing sheets directly from PDF.

Architecture: Five Phases in Order

Execute in five sequential phases. Each phase has a defined output that must be completed before the next begins. Do not skip phases or combine them. The most common failure mode is attempting Phase 4 (writing) before Phase 3 (validation) is complete.

Subcontract Writer Progress:
Phase 1  →  Phase 2  →  Phase 3  →  USER CHECKPOINT  →  Phase 4  →  Phase 5
Triage     Extract     Validate      Confirm data         Write       Verify

Phase 1 — Document Triage and Slot Assignment

Before reading any document substantively, assign each uploaded file to its slot. State the assignments to the user before proceeding.

Slot B is mandatory. If missing, stop and output:

I need the awarded subcontractor's bid document before I can generate this
subcontract. The bid is the source of truth for the contract sum, quantities,
and unit rates. Which file is the awarded bid?

Read Slot A first to understand the required article structure. Note every article heading. Flag any article that requires project-specific content (not just boilerplate) — these become required extraction targets in Phase 2.

If no template is provided, ask: "Do you have a standard subcontract template?" If none available, use AIA A401-style structure as fallback.

Phase 2 — Structured Extraction, One Slot at a Time

Run a separate extraction pass for each slot. Write extracted data to .construction/skills/subcontract-writer/scope_data.json incrementally. Do not combine slots in a single read.

A text dump is working data: take pdf_text.py's output directly, or, to search it more than once, save it with --output under .construction/skills/subcontract-writer/text/, never in /tmp or any other folder outside the project.

Slot B Extraction (Bid Document) — Run First

Dump the bid's text first; read TEXT pages from the dump and rasterize VISION pages for vision reading:

"${CLAUDE_PLUGIN_ROOT}/bin/construction-python" "${CLAUDE_PLUGIN_ROOT}/scripts/pdf/pdf_text.py" "{bid.pdf}"

Extract every field below. Mark any field not found as MISSING — do not infer or estimate.

Commercial data:

• Subcontractor company name (exact legal name from letterhead)
• Address, phone, email
• License/registration number
• Estimator/contact name
• Proposal number and date
• Bid validity period (if stated)
• Total contract sum (exact dollar amount)

Scope data:

• Line items with: spec section, description, quantity, unit, unit rate, extended amount
• Inclusions list (verbatim from bid)
• Exclusions list (verbatim from bid — critical for scope gap prevention)
• Value engineering alternates with VE ID, description, and deduct amount
• Qualifications or clarifications

Verify: Line item amounts must sum to the total contract sum. If they don't, flag the discrepancy.

Slot A Extraction (Template)

If .docx template: dump it (paragraphs with their styles, then tables) and read the article structure and fill-field placeholders from the dump:

"${CLAUDE_PLUGIN_ROOT}/bin/construction-python" "${CLAUDE_PLUGIN_ROOT}/scripts/docx_text.py" "{template.docx}"

If PDF template: Use vision to read the template. Rasterize pages if needed:

"${CLAUDE_PLUGIN_ROOT}/bin/construction-python" "${CLAUDE_PLUGIN_ROOT}/scripts/pdf/rasterize_page.py" "template.pdf" {page} --dpi 200 --output ".construction/skills/subcontract-writer/pages/template_page_{page}.png"

Extract the list of required articles and any fill-field placeholders ([DATE], [CONTRACT SUM], [SUBCONTRACTOR]).

For each article, determine:

• number and title (exactly as shown in template)
• content_type: one of:
• "preserve" — standard boilerplate (payment terms, insurance, dispute resolution, indemnity, safety, default/termination, general provisions). Transcribe the EXACT text verbatim.
• "generate" — scope-specific content (scope of work, contract documents, schedule, submittals, warranty). You will write this from extracted data.
• "fill-in" — project-specific values (contract sum, dates). You will populate from the Data Model.

Critical: Transcribe ALL preserved article text verbatim. Do not summarize or paraphrase template boilerplate.

Slot C Extraction (Specifications)

For each specification section listed in the bid scope, read its text and extract Part 1 requirements. One extraction block per section. Where the text comes from depends on the mode:

• AgentCM mode: .construction/specs/<section>.txt is the section's text. Never run pdf_text.py or rasterize_page.py on that section's pages: not to check them, and not as part of a page range. A read manual's pages in no section (INDEX.md lists them) are read in the PDF, those pages only (--pages).
• Flat-file mode: dump the section PDF with pdf_text.py, as for the bid. To search the sections for submittals, warranties or qualifications, save each dump first (--output ".construction/skills/subcontract-writer/text/<section>.txt") and search those files.

Extract per spec section:

• §1.3 / §1.4 — Submittal requirements: shop drawings, product data, samples, certifications, LEED docs
• §1.5 — Quality assurance: installer qualifications, manufacturer certifications, mockups, testing
• §1.6 / §1.8 — Warranty provisions: general warranty period, extended warranties, joint manufacturer/installer warranties
• §1.7 — Special conditions: environmental requirements (temperature, humidity, cure times), substrate conditions
• §3.x — Execution requirements: installation methods, tolerances, protection requirements

Also check Division 01 for project-wide requirements: MBE/WBE goals, prevailing wage, LEED, closeout documents.

Slot D Extraction (Drawings/Finish Schedule) — If Provided

Extract room/area codes relevant to scope boundaries. Identify explicit exclusions (rooms marked "by others" or scoped to a different trade). This extraction is scope-dependent — only extract data relevant to the trade being contracted.

Phase 3 — Data Validation

Before surfacing anything to the user, validate the extracted data. Every MISSING field in a required category is a blocking error.

Required Fields (blocking — cannot proceed if absent)

Spec-specific requirements are conditional — only required if that spec section appears in the bid scope.

Legal Completeness Checks

• Contract sum written words matches numeral mathematically
• Schedule of values quantities match bid document (not master scope estimates)
• No quantity in SOV differs from the bid by more than 2%
• VE alternates list is complete (check all bid pages — VE alternates often appear on page 2+)
• Exclusions cross-checked against drawings (if Slot D provided)

Compute Derived Fields

After validation, compute fields the user will need to confirm:

USER CHECKPOINT — Show Data Model, Wait for Confirmation

This is the most important step in the skill. Do not skip it.

After Phase 3 validation passes, surface the complete extracted data to the user in readable format before writing any contract prose. The user must explicitly confirm or correct the data.

Format the checkpoint output:

I've read all [N] documents. Here's what I extracted — please review before
I generate the subcontract.
 
━━━ SUBCONTRACTOR ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Company:       [company_name]
  License:       [license_number]
  Proposal:      [proposal_number]  (dated [bid_date])
  Estimator:     [estimator_name]  ·  [email]  ·  [phone]