contractor-bid 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (139) hide show
  1. contractor_bid-0.2.0/.claude-plugin/marketplace.json +13 -0
  2. contractor_bid-0.2.0/.claude-plugin/plugin.json +19 -0
  3. contractor_bid-0.2.0/.cursor-plugin/plugin.json +30 -0
  4. contractor_bid-0.2.0/.gitignore +37 -0
  5. contractor_bid-0.2.0/.mcp.json +8 -0
  6. contractor_bid-0.2.0/AGENTS.md +66 -0
  7. contractor_bid-0.2.0/CLAUDE.md +5 -0
  8. contractor_bid-0.2.0/LICENSE +21 -0
  9. contractor_bid-0.2.0/PKG-INFO +402 -0
  10. contractor_bid-0.2.0/README.md +387 -0
  11. contractor_bid-0.2.0/codex-marketplace.json +18 -0
  12. contractor_bid-0.2.0/commands/check.md +7 -0
  13. contractor_bid-0.2.0/commands/new-bid.md +11 -0
  14. contractor_bid-0.2.0/commands/triage.md +10 -0
  15. contractor_bid-0.2.0/docs/CSI_DIVISIONS.md +65 -0
  16. contractor_bid-0.2.0/docs/MCP_PLUGIN.md +129 -0
  17. contractor_bid-0.2.0/docs/SELF_LEARNING.md +36 -0
  18. contractor_bid-0.2.0/docs/WHAT_YOU_GET.md +43 -0
  19. contractor_bid-0.2.0/docs/WORKFLOW.md +63 -0
  20. contractor_bid-0.2.0/docs/assets/contractor-bid-flow.svg +118 -0
  21. contractor_bid-0.2.0/examples/agent-session.md +102 -0
  22. contractor_bid-0.2.0/examples/profiles/concrete-flatwork.json +16 -0
  23. contractor_bid-0.2.0/examples/profiles/division-03-concrete.json +68 -0
  24. contractor_bid-0.2.0/examples/profiles/division-04-masonry.json +64 -0
  25. contractor_bid-0.2.0/examples/profiles/division-05-metals.json +68 -0
  26. contractor_bid-0.2.0/examples/profiles/division-06-wood-plastics-composites.json +64 -0
  27. contractor_bid-0.2.0/examples/profiles/division-07-thermal-moisture-protection.json +68 -0
  28. contractor_bid-0.2.0/examples/profiles/division-08-openings.json +67 -0
  29. contractor_bid-0.2.0/examples/profiles/division-09-finishes.json +66 -0
  30. contractor_bid-0.2.0/examples/profiles/division-10-specialties.json +65 -0
  31. contractor_bid-0.2.0/examples/profiles/division-11-equipment.json +64 -0
  32. contractor_bid-0.2.0/examples/profiles/division-12-furnishings.json +64 -0
  33. contractor_bid-0.2.0/examples/profiles/division-13-special-construction.json +65 -0
  34. contractor_bid-0.2.0/examples/profiles/division-14-conveying-equipment.json +63 -0
  35. contractor_bid-0.2.0/examples/profiles/division-21-fire-suppression.json +63 -0
  36. contractor_bid-0.2.0/examples/profiles/division-22-plumbing.json +64 -0
  37. contractor_bid-0.2.0/examples/profiles/division-23-hvac.json +69 -0
  38. contractor_bid-0.2.0/examples/profiles/division-25-integrated-automation.json +64 -0
  39. contractor_bid-0.2.0/examples/profiles/division-26-electrical.json +66 -0
  40. contractor_bid-0.2.0/examples/profiles/division-27-communications.json +65 -0
  41. contractor_bid-0.2.0/examples/profiles/division-28-electronic-safety-security.json +66 -0
  42. contractor_bid-0.2.0/examples/profiles/division-31-earthwork.json +67 -0
  43. contractor_bid-0.2.0/examples/profiles/division-32-exterior-improvements.json +69 -0
  44. contractor_bid-0.2.0/examples/profiles/division-33-utilities.json +68 -0
  45. contractor_bid-0.2.0/examples/profiles/drywall-framing.json +16 -0
  46. contractor_bid-0.2.0/examples/profiles/electrical.json +16 -0
  47. contractor_bid-0.2.0/examples/profiles/fences-gates.json +16 -0
  48. contractor_bid-0.2.0/examples/profiles/hvac.json +70 -0
  49. contractor_bid-0.2.0/examples/profiles/plumbing.json +65 -0
  50. contractor_bid-0.2.0/examples/profiles/roofing.json +68 -0
  51. contractor_bid-0.2.0/packaging/homebrew/README.md +24 -0
  52. contractor_bid-0.2.0/packaging/homebrew/contractor-bid.rb +40 -0
  53. contractor_bid-0.2.0/profiles/README.md +27 -0
  54. contractor_bid-0.2.0/profiles/concrete-flatwork.json +16 -0
  55. contractor_bid-0.2.0/profiles/division-03-concrete.json +68 -0
  56. contractor_bid-0.2.0/profiles/division-04-masonry.json +64 -0
  57. contractor_bid-0.2.0/profiles/division-05-metals.json +68 -0
  58. contractor_bid-0.2.0/profiles/division-06-wood-plastics-composites.json +64 -0
  59. contractor_bid-0.2.0/profiles/division-07-thermal-moisture-protection.json +68 -0
  60. contractor_bid-0.2.0/profiles/division-08-openings.json +67 -0
  61. contractor_bid-0.2.0/profiles/division-09-finishes.json +66 -0
  62. contractor_bid-0.2.0/profiles/division-10-specialties.json +65 -0
  63. contractor_bid-0.2.0/profiles/division-11-equipment.json +64 -0
  64. contractor_bid-0.2.0/profiles/division-12-furnishings.json +64 -0
  65. contractor_bid-0.2.0/profiles/division-13-special-construction.json +65 -0
  66. contractor_bid-0.2.0/profiles/division-14-conveying-equipment.json +63 -0
  67. contractor_bid-0.2.0/profiles/division-21-fire-suppression.json +63 -0
  68. contractor_bid-0.2.0/profiles/division-22-plumbing.json +64 -0
  69. contractor_bid-0.2.0/profiles/division-23-hvac.json +69 -0
  70. contractor_bid-0.2.0/profiles/division-25-integrated-automation.json +64 -0
  71. contractor_bid-0.2.0/profiles/division-26-electrical.json +66 -0
  72. contractor_bid-0.2.0/profiles/division-27-communications.json +65 -0
  73. contractor_bid-0.2.0/profiles/division-28-electronic-safety-security.json +66 -0
  74. contractor_bid-0.2.0/profiles/division-31-earthwork.json +67 -0
  75. contractor_bid-0.2.0/profiles/division-32-exterior-improvements.json +69 -0
  76. contractor_bid-0.2.0/profiles/division-33-utilities.json +68 -0
  77. contractor_bid-0.2.0/profiles/drywall-framing.json +16 -0
  78. contractor_bid-0.2.0/profiles/electrical.json +16 -0
  79. contractor_bid-0.2.0/profiles/fences-gates.json +16 -0
  80. contractor_bid-0.2.0/profiles/hvac.json +16 -0
  81. contractor_bid-0.2.0/profiles/plumbing.json +16 -0
  82. contractor_bid-0.2.0/profiles/roofing.json +16 -0
  83. contractor_bid-0.2.0/pyproject.toml +71 -0
  84. contractor_bid-0.2.0/scripts/generate-csi-starters.py +94 -0
  85. contractor_bid-0.2.0/scripts/install.ps1 +78 -0
  86. contractor_bid-0.2.0/scripts/install.sh +123 -0
  87. contractor_bid-0.2.0/skills/README.md +13 -0
  88. contractor_bid-0.2.0/skills/bid-tracker/SKILL.md +99 -0
  89. contractor_bid-0.2.0/skills/concrete-flatwork-bid-scope/SKILL.md +62 -0
  90. contractor_bid-0.2.0/skills/division-03-concrete-bid-scope/SKILL.md +67 -0
  91. contractor_bid-0.2.0/skills/division-04-masonry-bid-scope/SKILL.md +65 -0
  92. contractor_bid-0.2.0/skills/division-05-metals-bid-scope/SKILL.md +66 -0
  93. contractor_bid-0.2.0/skills/division-06-wood-plastics-composites-bid-scope/SKILL.md +65 -0
  94. contractor_bid-0.2.0/skills/division-07-thermal-moisture-protection-bid-scope/SKILL.md +66 -0
  95. contractor_bid-0.2.0/skills/division-08-openings-bid-scope/SKILL.md +66 -0
  96. contractor_bid-0.2.0/skills/division-09-finishes-bid-scope/SKILL.md +65 -0
  97. contractor_bid-0.2.0/skills/division-10-specialties-bid-scope/SKILL.md +65 -0
  98. contractor_bid-0.2.0/skills/division-11-equipment-bid-scope/SKILL.md +65 -0
  99. contractor_bid-0.2.0/skills/division-12-furnishings-bid-scope/SKILL.md +64 -0
  100. contractor_bid-0.2.0/skills/division-13-special-construction-bid-scope/SKILL.md +65 -0
  101. contractor_bid-0.2.0/skills/division-14-conveying-equipment-bid-scope/SKILL.md +64 -0
  102. contractor_bid-0.2.0/skills/division-21-fire-suppression-bid-scope/SKILL.md +64 -0
  103. contractor_bid-0.2.0/skills/division-22-plumbing-bid-scope/SKILL.md +65 -0
  104. contractor_bid-0.2.0/skills/division-23-hvac-bid-scope/SKILL.md +66 -0
  105. contractor_bid-0.2.0/skills/division-25-integrated-automation-bid-scope/SKILL.md +65 -0
  106. contractor_bid-0.2.0/skills/division-26-electrical-bid-scope/SKILL.md +66 -0
  107. contractor_bid-0.2.0/skills/division-27-communications-bid-scope/SKILL.md +65 -0
  108. contractor_bid-0.2.0/skills/division-28-electronic-safety-security-bid-scope/SKILL.md +66 -0
  109. contractor_bid-0.2.0/skills/division-31-earthwork-bid-scope/SKILL.md +66 -0
  110. contractor_bid-0.2.0/skills/division-32-exterior-improvements-bid-scope/SKILL.md +66 -0
  111. contractor_bid-0.2.0/skills/division-33-utilities-bid-scope/SKILL.md +65 -0
  112. contractor_bid-0.2.0/skills/drywall-framing-bid-scope/SKILL.md +62 -0
  113. contractor_bid-0.2.0/skills/electrical-bid-scope/SKILL.md +63 -0
  114. contractor_bid-0.2.0/skills/fences-gates-bid-scope/SKILL.md +64 -0
  115. contractor_bid-0.2.0/skills/hvac-bid-scope/SKILL.md +72 -0
  116. contractor_bid-0.2.0/skills/plumbing-bid-scope/SKILL.md +69 -0
  117. contractor_bid-0.2.0/skills/roofing-bid-scope/SKILL.md +71 -0
  118. contractor_bid-0.2.0/src/contractor_bid/__init__.py +5 -0
  119. contractor_bid-0.2.0/src/contractor_bid/__main__.py +4 -0
  120. contractor_bid-0.2.0/src/contractor_bid/cli.py +506 -0
  121. contractor_bid-0.2.0/src/contractor_bid/csi_starters.py +1269 -0
  122. contractor_bid-0.2.0/src/contractor_bid/doctor.py +100 -0
  123. contractor_bid-0.2.0/src/contractor_bid/learning.py +42 -0
  124. contractor_bid-0.2.0/src/contractor_bid/mcp_server.py +845 -0
  125. contractor_bid-0.2.0/src/contractor_bid/packets.py +326 -0
  126. contractor_bid-0.2.0/src/contractor_bid/profile.py +185 -0
  127. contractor_bid-0.2.0/src/contractor_bid/project.py +101 -0
  128. contractor_bid-0.2.0/src/contractor_bid/sendoff.py +76 -0
  129. contractor_bid-0.2.0/src/contractor_bid/tracker.py +382 -0
  130. contractor_bid-0.2.0/src/contractor_bid/triage.py +483 -0
  131. contractor_bid-0.2.0/src/contractor_bid/util.py +90 -0
  132. contractor_bid-0.2.0/src/contractor_bid/validate.py +251 -0
  133. contractor_bid-0.2.0/src/contractor_bid/workbook.py +328 -0
  134. contractor_bid-0.2.0/templates/00-scope-reference-index-template.md +45 -0
  135. contractor_bid-0.2.0/templates/02-proposal-letter-template.md +48 -0
  136. contractor_bid-0.2.0/templates/project-readme-template.md +38 -0
  137. contractor_bid-0.2.0/templates/review-pages-template.md +7 -0
  138. contractor_bid-0.2.0/templates/scope-pages-sources-template.json +19 -0
  139. contractor_bid-0.2.0/templates/takeoff-template.json +48 -0
@@ -0,0 +1,13 @@
1
+ {
2
+ "name": "contractor-bid",
3
+ "owner": {
4
+ "name": "ContractorKeith"
5
+ },
6
+ "plugins": [
7
+ {
8
+ "name": "contractor-bid",
9
+ "source": "./",
10
+ "description": "AI-ready bid workspaces for commercial subcontractors."
11
+ }
12
+ ]
13
+ }
@@ -0,0 +1,19 @@
1
+ {
2
+ "name": "contractor-bid",
3
+ "version": "0.2.0",
4
+ "description": "AI-ready bid workspaces for commercial subcontractors. Triage plan sets, build scope/spec packets, takeoff workbooks, alerts, and supplier sendoffs.",
5
+ "author": {
6
+ "name": "ContractorKeith",
7
+ "url": "https://github.com/ContractorKeith"
8
+ },
9
+ "repository": "https://github.com/ContractorKeith/contractor-bid",
10
+ "license": "MIT",
11
+ "keywords": [
12
+ "construction",
13
+ "estimating",
14
+ "bidding",
15
+ "csi",
16
+ "subcontractor",
17
+ "takeoff"
18
+ ]
19
+ }
@@ -0,0 +1,30 @@
1
+ {
2
+ "name": "contractor-bid",
3
+ "version": "0.2.0",
4
+ "description": "AI-ready bid workspaces for commercial subcontractors.",
5
+ "author": {
6
+ "name": "ContractorKeith",
7
+ "url": "https://github.com/ContractorKeith"
8
+ },
9
+ "repository": "https://github.com/ContractorKeith/contractor-bid",
10
+ "license": "MIT",
11
+ "skills": [
12
+ "skills"
13
+ ],
14
+ "commands": [
15
+ "commands"
16
+ ],
17
+ "mcpServers": {
18
+ "contractor-bid": {
19
+ "command": "contractor-bid-mcp",
20
+ "args": []
21
+ }
22
+ },
23
+ "keywords": [
24
+ "construction",
25
+ "estimating",
26
+ "bidding",
27
+ "csi",
28
+ "subcontractor"
29
+ ]
30
+ }
@@ -0,0 +1,37 @@
1
+ .DS_Store
2
+ __pycache__/
3
+ *.py[cod]
4
+ .pytest_cache/
5
+ .ruff_cache/
6
+ .mypy_cache/
7
+ .venv/
8
+ venv/
9
+ dist/
10
+ build/
11
+ *.egg-info/
12
+
13
+ # Generated bid-project artifacts
14
+ **/bid-docs/
15
+ **/bid-package-working/page-images/
16
+ **/bid-package-working/text-extracts/
17
+ **/bid-package-working/*.pdf
18
+ **/bid-package-working/*.xlsx
19
+ **/bid-package-working/supplier-sendoff/
20
+
21
+ # Local user/company configuration
22
+ .contractor-bid/local.json
23
+ .contractor-bid/feedback.jsonl
24
+
25
+ # Bid tracker (holds the user's real bid pipeline — do not commit)
26
+ .contractor-bid/bid-tracker.json
27
+ Bid-Tracker.xlsx
28
+
29
+ # Local handover notes
30
+ handover.md
31
+ HANDOVER.md
32
+ handover-*.md
33
+ handovers/
34
+
35
+ # Local planning / working notes (not for publication)
36
+ IMPROVEMENT_PLAN.md
37
+ mcp-plugin-planning.md
@@ -0,0 +1,8 @@
1
+ {
2
+ "mcpServers": {
3
+ "contractor-bid": {
4
+ "command": "contractor-bid-mcp",
5
+ "args": []
6
+ }
7
+ }
8
+ }
@@ -0,0 +1,66 @@
1
+ # Agent Instructions
2
+
3
+ This repo builds AI-ready commercial subcontractor bid projects.
4
+
5
+ ## Operating Rules
6
+
7
+ - Read `profiles/<profile>.json` and `skills/<profile>-bid-scope/SKILL.md` before making scope calls.
8
+ - Built-in starter profiles include canonical `division-XX-*` profiles for every active CSI MasterFormat division from 03 through 33. Read `docs/CSI_DIVISIONS.md` when selecting a starter.
9
+ - Trade-specific examples such as `fences-gates`, `concrete-flatwork`, `drywall-framing`, `electrical`, `plumbing`, `hvac`, and `roofing` are narrower examples, not the full CSI coverage set.
10
+ - If none of the starter profiles fit, run `contractor-bid init` to create a custom profile and matching skill.
11
+ - Source PDFs and bid forms belong in `bid-docs/`; generated artifacts belong in `bid-package-working/`.
12
+ - Treat `takeoff/*.json` as the source of truth for workbook generation.
13
+ - Do not silently include excluded or review-only adjacent scopes in base bid.
14
+ - Carry the same scope boundary through the summary, reference index, workbook, proposal letter, alerts, and sendoff.
15
+ - Record user corrections with `contractor-bid learn`; only update durable profile rules when the user confirms the correction should persist.
16
+ - Keep the workspace bid tracker current with the `track-*` commands, but ALWAYS confirm with the user and show a one-line change summary before writing (see `skills/bid-tracker/SKILL.md`).
17
+
18
+ ## Standard Pipeline
19
+
20
+ ```bash
21
+ contractor-bid doctor
22
+ contractor-bid triage <project> --profile <profile> --render
23
+ # Human review: open candidate-pages.md and scope-pages-sources.suggested.json.
24
+ # Copy/merge approved pages into takeoff/scope-pages-sources.json.
25
+ contractor-bid build-packets <project>
26
+ # Human review: fill the takeoff/BOM JSON from source-backed quantities and quotes.
27
+ contractor-bid build-workbook <project> --profile <profile>
28
+ contractor-bid check <project> --profile <profile>
29
+ contractor-bid package-sendoff <project>
30
+ ```
31
+
32
+ Use `contractor-bid status <project> --profile <profile>` for a non-writing readiness check,
33
+ or `contractor-bid run <project> --profile <profile>` after the two human-fill steps are done.
34
+
35
+ ## Bid Tracker
36
+
37
+ Maintain a workspace-wide pipeline view with the `track-*` commands. Source of truth is
38
+ `.contractor-bid/bid-tracker.json`; the readable sheet is `Bid-Tracker.xlsx` (Active Bids +
39
+ Archived & Completed). Read `skills/bid-tracker/SKILL.md` first.
40
+
41
+ Hard rule: never write to the tracker silently. Before any `track-add`, `track-update`,
42
+ `track-move`, or `track-reopen`, show the user a one-line summary of the change and wait for
43
+ confirmation. `track-list` and `track-build` are read-only.
44
+
45
+ ```bash
46
+ contractor-bid track-add bids/<project> --progress Triage # add a bid (pulls project.json)
47
+ contractor-bid track-update "<bid>" --progress Submitted --next "Follow up Friday"
48
+ contractor-bid track-move "<bid>" --outcome won # moves it to Archived & Completed
49
+ contractor-bid track-list # read-only
50
+ ```
51
+
52
+ ## Review Before Pricing
53
+
54
+ - Latest addendum/revision basis.
55
+ - Manual measurements and quantity basis.
56
+ - Scope exclusions and review-only terms.
57
+ - Alternates versus base bid.
58
+ - GC bid-form requirements.
59
+ - Supplier quote inputs and lead times.
60
+
61
+ ## Installation Assumptions
62
+
63
+ - Normal users install with `scripts/install.sh` or `scripts/install.ps1`.
64
+ - Python package dependencies are installed into the contractor-bid virtualenv.
65
+ - Poppler is recommended for PDF extraction/rendering; without it, `pypdf` fallback works for some PDFs but page images are unavailable.
66
+ - GitHub CLI is not required for normal use.
@@ -0,0 +1,5 @@
1
+ # Claude Compatibility
2
+
3
+ Read `AGENTS.md` first. It is the canonical agent workflow for this repository.
4
+
5
+ Claude-specific reminder: do not invent final quantities from PDF text hits. Text hits are triage evidence only; quantities require source-backed measurement or a stated manual placeholder.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ContractorKeith
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,402 @@
1
+ Metadata-Version: 2.4
2
+ Name: contractor-bid
3
+ Version: 0.2.0
4
+ Summary: AI-ready commercial construction bid project starter kit for subcontractors in any CSI division.
5
+ Author: ContractorKeith
6
+ License-Expression: MIT
7
+ License-File: LICENSE
8
+ Keywords: ai,bid,construction,csi,estimating,subcontractor,takeoff
9
+ Requires-Python: >=3.11
10
+ Requires-Dist: openpyxl>=3.1
11
+ Requires-Dist: pypdf>=4.0
12
+ Provides-Extra: mcp
13
+ Requires-Dist: mcp>=1.8.1; extra == 'mcp'
14
+ Description-Content-Type: text/markdown
15
+
16
+ # contractor-bid
17
+
18
+ [![CI](https://github.com/ContractorKeith/contractor-bid/actions/workflows/ci.yml/badge.svg)](https://github.com/ContractorKeith/contractor-bid/actions/workflows/ci.yml)
19
+
20
+ AI-ready bid workspaces for commercial subcontractors.
21
+
22
+ > **Status: early access / in active development (v0.2.0).** This is a public testing
23
+ > release shared to gather real-world feedback. Expect rough edges, and verify every
24
+ > output against the source documents before pricing a real bid. Bug reports and
25
+ > contributions are welcome and encouraged — please
26
+ > [open an issue](https://github.com/ContractorKeith/contractor-bid/issues) or see
27
+ > [CONTRIBUTING.md](CONTRIBUTING.md).
28
+
29
+ ![contractor-bid workflow](docs/assets/contractor-bid-flow.svg)
30
+
31
+ Commercial bid folders are usually messy: large plan sets, project manuals, addenda, bid forms, scope gaps, and adjacent trades that can accidentally drift into your number. `contractor-bid` gives a subcontractor a repeatable project structure that an AI agent can work inside without losing the audit trail.
32
+
33
+ If this saves you bid setup time, star the repo so more subcontractors can find it.
34
+
35
+ It does not price the job for you. It helps turn bid documents into a reviewable package: relevant pages, source-backed summaries, workbook inputs, proposal language, alerts, and a sendoff folder.
36
+
37
+ ## What This Repo Does
38
+
39
+ `contractor-bid` is a Python CLI plus an optional MCP server, agent instructions,
40
+ templates, starter trade profiles, and validation checks.
41
+
42
+ Use it when you want to open Claude, Codex, or another model and say:
43
+
44
+ ```text
45
+ Start a new bid project for my electrical scope.
46
+ ```
47
+
48
+ The project gives the model a structure to follow:
49
+
50
+ 1. Ask or load the subcontractor's CSI division and scope rules.
51
+ 2. Create a bid project folder.
52
+ 3. Put source documents in `bid-docs/`.
53
+ 4. Triage PDFs for likely scope/spec pages.
54
+ 5. Build a short page packet and quick-read summary.
55
+ 6. Build a takeoff/BOM workbook from JSON.
56
+ 7. Check for missing artifacts, addenda, and scope drift.
57
+ 8. Package a supplier or internal-review sendoff.
58
+ 9. Record corrections so the next bid gets better.
59
+
60
+ ## What You Get
61
+
62
+ Each bid project is built around `bid-package-working/`:
63
+
64
+ | File | Purpose |
65
+ |---|---|
66
+ | `00-Bid-Scope-Summary.md` | First-read summary: what it is, where it is, what to open first, what is excluded, and what needs clarification. |
67
+ | `00-Scope-Reference-Index.md` | Drawing/spec/RFI index for the carried scope. |
68
+ | `scope-pages.pdf` | Isolated drawing pages relevant to the subcontractor's scope. |
69
+ | `spec-pages.pdf` | Isolated spec pages when specs are found. |
70
+ | `scope-and-spec-pages.pdf` | Combined page packet for review or supplier handoff. |
71
+ | `01-Takeoff-Worksheet-REV1.xlsx` | Workbook with BOM rows, supplier quote inputs, RFIs, alerts, and sources. |
72
+ | `02 - Proposal Letter.md` | Draft proposal language with inclusions, exclusions, alternates, and clarifications. |
73
+ | `ALERTS.md` | Validator output for missing deliverables, due dates, addenda, and excluded/review-only scope terms. |
74
+ | `supplier-sendoff/*.zip` | Shareable package for vendors, suppliers, or internal review. |
75
+
76
+ The pattern comes from real fence/gate bid work. In one package, the workflow produced a scope PDF, a spec PDF, a combined packet, a workbook, alerts, and a supplier zip. In another smaller package, the scope packet was only a few pages and no separate spec packet was needed. The structure stayed the same, which is what lets the model and estimator stay aligned.
77
+
78
+ More detail: [What A Bid Project Produces](docs/WHAT_YOU_GET.md).
79
+
80
+ ## Who It Is For
81
+
82
+ - Commercial subcontractors in any CSI division.
83
+ - Estimators who want AI help but still need source-backed files.
84
+ - Contractors building repeatable bid workflows.
85
+ - Developers building trade-specific AI agents for construction.
86
+
87
+ Canonical starter profiles are included for the active CSI MasterFormat divisions from 03 through 33:
88
+
89
+ | CSI division | Profile |
90
+ |---|---|
91
+ | 03 - Concrete | `division-03-concrete` |
92
+ | 04 - Masonry | `division-04-masonry` |
93
+ | 05 - Metals | `division-05-metals` |
94
+ | 06 - Wood, Plastics, and Composites | `division-06-wood-plastics-composites` |
95
+ | 07 - Thermal and Moisture Protection | `division-07-thermal-moisture-protection` |
96
+ | 08 - Openings | `division-08-openings` |
97
+ | 09 - Finishes | `division-09-finishes` |
98
+ | 10 - Specialties | `division-10-specialties` |
99
+ | 11 - Equipment | `division-11-equipment` |
100
+ | 12 - Furnishings | `division-12-furnishings` |
101
+ | 13 - Special Construction | `division-13-special-construction` |
102
+ | 14 - Conveying Equipment | `division-14-conveying-equipment` |
103
+ | 21 - Fire Suppression | `division-21-fire-suppression` |
104
+ | 22 - Plumbing | `division-22-plumbing` |
105
+ | 23 - Heating, Ventilating, and Air Conditioning (HVAC) | `division-23-hvac` |
106
+ | 25 - Integrated Automation | `division-25-integrated-automation` |
107
+ | 26 - Electrical | `division-26-electrical` |
108
+ | 27 - Communications | `division-27-communications` |
109
+ | 28 - Electronic Safety and Security | `division-28-electronic-safety-security` |
110
+ | 31 - Earthwork | `division-31-earthwork` |
111
+ | 32 - Exterior Improvements | `division-32-exterior-improvements` |
112
+ | 33 - Utilities | `division-33-utilities` |
113
+
114
+ Divisions 15-20, 24, 29, and 30 are reserved in this range, so they are documented but do not get bid starters. More detail: [CSI Division Starters](docs/CSI_DIVISIONS.md).
115
+
116
+ The repo also keeps narrower trade-specific examples like `fences-gates`, `concrete-flatwork`, `drywall-framing`, `electrical`, `plumbing`, `hvac`, and `roofing`.
117
+
118
+ Use `contractor-bid init` when your trade or company rules are different.
119
+
120
+ ## Install
121
+
122
+ ### Recommended: pipx
123
+
124
+ Install the CLI:
125
+
126
+ ```bash
127
+ pipx install contractor-bid
128
+ ```
129
+
130
+ Install the CLI plus MCP server for Claude Code, Codex, Cursor, or another MCP-capable agent:
131
+
132
+ ```bash
133
+ pipx install "contractor-bid[mcp]"
134
+ ```
135
+
136
+ This gives you both:
137
+
138
+ ```bash
139
+ contractor-bid doctor
140
+ contractor-bid-mcp
141
+ ```
142
+
143
+ ### macOS / Linux
144
+
145
+ From a source checkout:
146
+
147
+ ```bash
148
+ git clone https://github.com/ContractorKeith/contractor-bid.git
149
+ cd contractor-bid
150
+ scripts/install.sh --install-poppler
151
+ ```
152
+
153
+ Or use the one-line installer:
154
+
155
+ ```bash
156
+ bash -c "$(curl -fsSL https://raw.githubusercontent.com/ContractorKeith/contractor-bid/main/scripts/install.sh)"
157
+ ```
158
+
159
+ ### Windows PowerShell
160
+
161
+ ```powershell
162
+ git clone https://github.com/ContractorKeith/contractor-bid.git
163
+ cd contractor-bid
164
+ .\scripts\install.ps1 -InstallPoppler
165
+ ```
166
+
167
+ The installer creates an isolated virtualenv under `~/.contractor-bid`, installs the CLI there, and writes a launcher to `~/.local/bin/contractor-bid`.
168
+
169
+ ## Prerequisites
170
+
171
+ Required:
172
+
173
+ - Python 3.11 or newer
174
+ - Git, for install and updates
175
+ - `pipx`, for the recommended isolated package install path
176
+
177
+ Installed automatically into the virtualenv:
178
+
179
+ - `openpyxl`, for `.xlsx` takeoff workbooks
180
+ - `pypdf`, for page packet PDFs and PDF fallback parsing
181
+
182
+ Recommended system dependency:
183
+
184
+ - Poppler: `pdfinfo`, `pdftotext`, and `pdftoppm`
185
+
186
+ Poppler gives faster PDF text extraction and page-image rendering. Without Poppler, basic PDF handling can fall back to `pypdf`, but rendered candidate page images are unavailable. This project does not do OCR yet; scanned image-only plans need OCR before triage works well.
187
+
188
+ Check a machine:
189
+
190
+ ```bash
191
+ contractor-bid doctor
192
+ ```
193
+
194
+ No GitHub CLI is required for normal use.
195
+
196
+ ## Agent Plugin Setup
197
+
198
+ The plugin layer wraps the installed Python engine. Install the engine first:
199
+
200
+ ```bash
201
+ pipx install "contractor-bid[mcp]"
202
+ ```
203
+
204
+ Claude Code:
205
+
206
+ ```text
207
+ /plugin marketplace add ContractorKeith/contractor-bid
208
+ /plugin install contractor-bid@contractor-bid
209
+ ```
210
+
211
+ Codex and Cursor can reuse the same `contractor-bid-mcp` server and `skills/`. This repo
212
+ includes `.mcp.json`, `.claude-plugin/`, `codex-marketplace.json`, and
213
+ `.cursor-plugin/` metadata for direct Git-hosted or local install flows.
214
+
215
+ More detail: [MCP And Agent Plugin Setup](docs/MCP_PLUGIN.md).
216
+
217
+ ## Quick Start
218
+
219
+ Create a workspace for your bids:
220
+
221
+ ```bash
222
+ mkdir contractor-bid-workspace
223
+ cd contractor-bid-workspace
224
+ ```
225
+
226
+ Start a project from a built-in profile:
227
+
228
+ ```bash
229
+ contractor-bid new bids/070126-example-project \
230
+ --profile division-32-exterior-improvements \
231
+ --project-name "Example Project" \
232
+ --bid-due "2026-07-01 14:00"
233
+ ```
234
+
235
+ Put source PDFs and bid forms in:
236
+
237
+ ```text
238
+ bids/070126-example-project/bid-docs/
239
+ ```
240
+
241
+ Run the bid workflow:
242
+
243
+ ```bash
244
+ contractor-bid triage bids/070126-example-project --profile division-32-exterior-improvements --render --write-sources
245
+ contractor-bid build-packets bids/070126-example-project
246
+ contractor-bid build-workbook bids/070126-example-project --profile division-32-exterior-improvements
247
+ contractor-bid check bids/070126-example-project --profile division-32-exterior-improvements
248
+ contractor-bid package-sendoff bids/070126-example-project
249
+ ```
250
+
251
+ Triage writes its suggestions to `scope-pages-sources.suggested.json`. Review that file, then
252
+ merge the pages you approve into `scope-pages-sources.json` before `build-packets`. The
253
+ `--write-sources` flag above only auto-fills `scope-pages-sources.json` while it is still empty;
254
+ once it has your content, triage leaves it alone. Triage suggestions are a starting point, not a
255
+ pricing decision.
256
+
257
+ Then open:
258
+
259
+ ```text
260
+ bids/070126-example-project/bid-package-working/00-Bid-Scope-Summary.md
261
+ ```
262
+
263
+ ## Custom Scope Profiles
264
+
265
+ Run:
266
+
267
+ ```bash
268
+ contractor-bid init
269
+ ```
270
+
271
+ That writes:
272
+
273
+ - `profiles/<profile>.json`
274
+ - `skills/<profile>-bid-scope/SKILL.md`
275
+
276
+ The profile defines:
277
+
278
+ - CSI division and spec section hints.
279
+ - Work carried in base bid.
280
+ - Search terms that identify the scope.
281
+ - Adjacent scope to exclude by default.
282
+ - Adjacent scope to flag before pricing.
283
+ - Standard proposal exclusions.
284
+
285
+ The generated skill is for Claude, Codex, or another model to read before making scope calls.
286
+
287
+ ## Test And Lint
288
+
289
+ For contributors:
290
+
291
+ ```bash
292
+ python3 -m pip install -e . ruff
293
+ python3 -m unittest discover -s tests
294
+ ruff check
295
+ ```
296
+
297
+ CI runs the same checks on Python 3.11 and 3.12.
298
+
299
+ ## Learning Loop
300
+
301
+ Record corrections:
302
+
303
+ ```bash
304
+ contractor-bid learn \
305
+ --profile fences-gates \
306
+ --project bids/070126-example-project \
307
+ --note "Flag motor operators separately when electrical power/control responsibility is unclear."
308
+ ```
309
+
310
+ The command appends to:
311
+
312
+ - `.contractor-bid/feedback.jsonl`
313
+ - `.contractor-bid/LESSONS.md`
314
+
315
+ Agents should review those files before similar bids. When a correction becomes a durable rule, update the profile, regenerated skill, templates, or validator.
316
+
317
+ ## Bid Tracker
318
+
319
+ Track every bid in flight on one readable spreadsheet. The tracker spans the whole workspace, not a single project.
320
+
321
+ ```bash
322
+ contractor-bid track-add bids/070126-example-project --progress Triage
323
+ contractor-bid track-update "Example Project" --progress Submitted --next "Follow up Friday"
324
+ contractor-bid track-move "Example Project" --outcome won
325
+ contractor-bid track-list
326
+ ```
327
+
328
+ This writes `.contractor-bid/bid-tracker.json` (source of truth) and regenerates `Bid-Tracker.xlsx`:
329
+
330
+ - **Active Bids** — Project, Location, Due, Progress, Next Action, Client / GC, Updated. Due dates within two days are amber; past-due are red.
331
+ - **Archived & Completed** — finished bids move here automatically with an outcome (won, lost, no-bid, completed).
332
+
333
+ The `bid-tracker` skill lets Claude, Codex, or another agent keep the tracker current as you work — and it asks for confirmation with a change summary before every write. Both tracker files are gitignored so your bid pipeline stays private.
334
+
335
+ ## Architecture
336
+
337
+ `contractor-bid` is a small, dependency-light Python CLI. The design rule is simple: **JSON files are the source of truth, and the scripts are deterministic glue that turn them into reviewable artifacts.** An AI agent reads the scope profile and skill, fills the JSON, and runs the commands — so every output traces back to a source page or a stated assumption.
338
+
339
+ ### Per-bid data flow
340
+
341
+ ```
342
+ profiles/<id>.json ─┐
343
+ bid-docs/*.pdf ─┴─► triage ──► candidate-pages.md + scope-pages-sources.suggested.json
344
+
345
+ takeoff/scope-pages-sources.json ─────┴──► build-packets ──► scope/spec PDFs + 00-Bid-Scope-Summary.md
346
+ takeoff/<project>.json ──────────► build-workbook ─► 01-Takeoff-Worksheet-REV1.xlsx
347
+
348
+ check ──► ALERTS.md ──► package-sendoff ──► supplier-sendoff/*.zip
349
+ ```
350
+
351
+ The bid tracker is a separate, workspace-level layer: `.contractor-bid/bid-tracker.json` → `Bid-Tracker.xlsx`.
352
+
353
+ ### Repository layout
354
+
355
+ ```
356
+ contractor-bid/
357
+ ├── src/contractor_bid/ # the CLI package (one module per command area)
358
+ │ ├── cli.py # argparse entrypoint; dispatches each subcommand
359
+ │ ├── profile.py # scope-profile schema + skill generation (render_skill)
360
+ │ ├── project.py # `new` — scaffolds a bid project folder from templates
361
+ │ ├── triage.py # PDF text extraction + candidate-page scoring
362
+ │ ├── packets.py # `build-packets` — scope/spec PDFs + quick-read summary
363
+ │ ├── workbook.py # `build-workbook` — styled takeoff/BOM .xlsx
364
+ │ ├── validate.py # `check` / `status` — deliverable + scope-drift checks
365
+ │ ├── sendoff.py # `package-sendoff` — supplier zip
366
+ │ ├── tracker.py # bid tracker (track-* commands)
367
+ │ ├── learning.py # `learn` — correction/feedback log
368
+ │ ├── doctor.py # `doctor` — environment checks
369
+ │ └── util.py # shared helpers
370
+ ├── profiles/<id>.json # built-in scope profiles (one per trade / CSI division)
371
+ ├── skills/<id>-bid-scope/ # generated agent skills (one per profile)
372
+ ├── skills/bid-tracker/ # workflow skill for the bid tracker
373
+ ├── examples/profiles/ # example profiles with sample company names
374
+ ├── templates/ # project file templates copied by `new`
375
+ ├── docs/ # workflow / what-you-get / self-learning docs
376
+ ├── scripts/ # install.sh / install.ps1
377
+ └── tests/ # unittest suite (incl. profile round-trip)
378
+ ```
379
+
380
+ ### Adding a trade or CSI division
381
+
382
+ A division is three files: `profiles/<id>.json`, the matching `skills/<id>-bid-scope/SKILL.md` (generated from the profile so `tests/test_profile_roundtrip.py` stays green), and `examples/profiles/<id>.json`. Run `contractor-bid init` to generate them interactively, or copy an existing starter and edit the scope terms.
383
+
384
+ ## Limitations
385
+
386
+ - Not a final pricing engine.
387
+ - Not a legal or contract-review tool.
388
+ - Not a substitute for manual measurement.
389
+ - Not an OCR pipeline for scanned drawings.
390
+ - Not a guarantee that every relevant sheet was found.
391
+
392
+ The intended use is practical: reduce the time between "I received a bid invite" and "I have a source-backed package I can review and price."
393
+
394
+ ## Contributing
395
+
396
+ See [CONTRIBUTING.md](CONTRIBUTING.md). Public examples should be fictional or sanitized. Do not commit proprietary bid documents, supplier quotes, private estimates, or customer files.
397
+
398
+ This project follows a [Code of Conduct](CODE_OF_CONDUCT.md).
399
+
400
+ ## License
401
+
402
+ MIT. See [LICENSE](LICENSE).