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.
- contractor_bid-0.2.0/.claude-plugin/marketplace.json +13 -0
- contractor_bid-0.2.0/.claude-plugin/plugin.json +19 -0
- contractor_bid-0.2.0/.cursor-plugin/plugin.json +30 -0
- contractor_bid-0.2.0/.gitignore +37 -0
- contractor_bid-0.2.0/.mcp.json +8 -0
- contractor_bid-0.2.0/AGENTS.md +66 -0
- contractor_bid-0.2.0/CLAUDE.md +5 -0
- contractor_bid-0.2.0/LICENSE +21 -0
- contractor_bid-0.2.0/PKG-INFO +402 -0
- contractor_bid-0.2.0/README.md +387 -0
- contractor_bid-0.2.0/codex-marketplace.json +18 -0
- contractor_bid-0.2.0/commands/check.md +7 -0
- contractor_bid-0.2.0/commands/new-bid.md +11 -0
- contractor_bid-0.2.0/commands/triage.md +10 -0
- contractor_bid-0.2.0/docs/CSI_DIVISIONS.md +65 -0
- contractor_bid-0.2.0/docs/MCP_PLUGIN.md +129 -0
- contractor_bid-0.2.0/docs/SELF_LEARNING.md +36 -0
- contractor_bid-0.2.0/docs/WHAT_YOU_GET.md +43 -0
- contractor_bid-0.2.0/docs/WORKFLOW.md +63 -0
- contractor_bid-0.2.0/docs/assets/contractor-bid-flow.svg +118 -0
- contractor_bid-0.2.0/examples/agent-session.md +102 -0
- contractor_bid-0.2.0/examples/profiles/concrete-flatwork.json +16 -0
- contractor_bid-0.2.0/examples/profiles/division-03-concrete.json +68 -0
- contractor_bid-0.2.0/examples/profiles/division-04-masonry.json +64 -0
- contractor_bid-0.2.0/examples/profiles/division-05-metals.json +68 -0
- contractor_bid-0.2.0/examples/profiles/division-06-wood-plastics-composites.json +64 -0
- contractor_bid-0.2.0/examples/profiles/division-07-thermal-moisture-protection.json +68 -0
- contractor_bid-0.2.0/examples/profiles/division-08-openings.json +67 -0
- contractor_bid-0.2.0/examples/profiles/division-09-finishes.json +66 -0
- contractor_bid-0.2.0/examples/profiles/division-10-specialties.json +65 -0
- contractor_bid-0.2.0/examples/profiles/division-11-equipment.json +64 -0
- contractor_bid-0.2.0/examples/profiles/division-12-furnishings.json +64 -0
- contractor_bid-0.2.0/examples/profiles/division-13-special-construction.json +65 -0
- contractor_bid-0.2.0/examples/profiles/division-14-conveying-equipment.json +63 -0
- contractor_bid-0.2.0/examples/profiles/division-21-fire-suppression.json +63 -0
- contractor_bid-0.2.0/examples/profiles/division-22-plumbing.json +64 -0
- contractor_bid-0.2.0/examples/profiles/division-23-hvac.json +69 -0
- contractor_bid-0.2.0/examples/profiles/division-25-integrated-automation.json +64 -0
- contractor_bid-0.2.0/examples/profiles/division-26-electrical.json +66 -0
- contractor_bid-0.2.0/examples/profiles/division-27-communications.json +65 -0
- contractor_bid-0.2.0/examples/profiles/division-28-electronic-safety-security.json +66 -0
- contractor_bid-0.2.0/examples/profiles/division-31-earthwork.json +67 -0
- contractor_bid-0.2.0/examples/profiles/division-32-exterior-improvements.json +69 -0
- contractor_bid-0.2.0/examples/profiles/division-33-utilities.json +68 -0
- contractor_bid-0.2.0/examples/profiles/drywall-framing.json +16 -0
- contractor_bid-0.2.0/examples/profiles/electrical.json +16 -0
- contractor_bid-0.2.0/examples/profiles/fences-gates.json +16 -0
- contractor_bid-0.2.0/examples/profiles/hvac.json +70 -0
- contractor_bid-0.2.0/examples/profiles/plumbing.json +65 -0
- contractor_bid-0.2.0/examples/profiles/roofing.json +68 -0
- contractor_bid-0.2.0/packaging/homebrew/README.md +24 -0
- contractor_bid-0.2.0/packaging/homebrew/contractor-bid.rb +40 -0
- contractor_bid-0.2.0/profiles/README.md +27 -0
- contractor_bid-0.2.0/profiles/concrete-flatwork.json +16 -0
- contractor_bid-0.2.0/profiles/division-03-concrete.json +68 -0
- contractor_bid-0.2.0/profiles/division-04-masonry.json +64 -0
- contractor_bid-0.2.0/profiles/division-05-metals.json +68 -0
- contractor_bid-0.2.0/profiles/division-06-wood-plastics-composites.json +64 -0
- contractor_bid-0.2.0/profiles/division-07-thermal-moisture-protection.json +68 -0
- contractor_bid-0.2.0/profiles/division-08-openings.json +67 -0
- contractor_bid-0.2.0/profiles/division-09-finishes.json +66 -0
- contractor_bid-0.2.0/profiles/division-10-specialties.json +65 -0
- contractor_bid-0.2.0/profiles/division-11-equipment.json +64 -0
- contractor_bid-0.2.0/profiles/division-12-furnishings.json +64 -0
- contractor_bid-0.2.0/profiles/division-13-special-construction.json +65 -0
- contractor_bid-0.2.0/profiles/division-14-conveying-equipment.json +63 -0
- contractor_bid-0.2.0/profiles/division-21-fire-suppression.json +63 -0
- contractor_bid-0.2.0/profiles/division-22-plumbing.json +64 -0
- contractor_bid-0.2.0/profiles/division-23-hvac.json +69 -0
- contractor_bid-0.2.0/profiles/division-25-integrated-automation.json +64 -0
- contractor_bid-0.2.0/profiles/division-26-electrical.json +66 -0
- contractor_bid-0.2.0/profiles/division-27-communications.json +65 -0
- contractor_bid-0.2.0/profiles/division-28-electronic-safety-security.json +66 -0
- contractor_bid-0.2.0/profiles/division-31-earthwork.json +67 -0
- contractor_bid-0.2.0/profiles/division-32-exterior-improvements.json +69 -0
- contractor_bid-0.2.0/profiles/division-33-utilities.json +68 -0
- contractor_bid-0.2.0/profiles/drywall-framing.json +16 -0
- contractor_bid-0.2.0/profiles/electrical.json +16 -0
- contractor_bid-0.2.0/profiles/fences-gates.json +16 -0
- contractor_bid-0.2.0/profiles/hvac.json +16 -0
- contractor_bid-0.2.0/profiles/plumbing.json +16 -0
- contractor_bid-0.2.0/profiles/roofing.json +16 -0
- contractor_bid-0.2.0/pyproject.toml +71 -0
- contractor_bid-0.2.0/scripts/generate-csi-starters.py +94 -0
- contractor_bid-0.2.0/scripts/install.ps1 +78 -0
- contractor_bid-0.2.0/scripts/install.sh +123 -0
- contractor_bid-0.2.0/skills/README.md +13 -0
- contractor_bid-0.2.0/skills/bid-tracker/SKILL.md +99 -0
- contractor_bid-0.2.0/skills/concrete-flatwork-bid-scope/SKILL.md +62 -0
- contractor_bid-0.2.0/skills/division-03-concrete-bid-scope/SKILL.md +67 -0
- contractor_bid-0.2.0/skills/division-04-masonry-bid-scope/SKILL.md +65 -0
- contractor_bid-0.2.0/skills/division-05-metals-bid-scope/SKILL.md +66 -0
- contractor_bid-0.2.0/skills/division-06-wood-plastics-composites-bid-scope/SKILL.md +65 -0
- contractor_bid-0.2.0/skills/division-07-thermal-moisture-protection-bid-scope/SKILL.md +66 -0
- contractor_bid-0.2.0/skills/division-08-openings-bid-scope/SKILL.md +66 -0
- contractor_bid-0.2.0/skills/division-09-finishes-bid-scope/SKILL.md +65 -0
- contractor_bid-0.2.0/skills/division-10-specialties-bid-scope/SKILL.md +65 -0
- contractor_bid-0.2.0/skills/division-11-equipment-bid-scope/SKILL.md +65 -0
- contractor_bid-0.2.0/skills/division-12-furnishings-bid-scope/SKILL.md +64 -0
- contractor_bid-0.2.0/skills/division-13-special-construction-bid-scope/SKILL.md +65 -0
- contractor_bid-0.2.0/skills/division-14-conveying-equipment-bid-scope/SKILL.md +64 -0
- contractor_bid-0.2.0/skills/division-21-fire-suppression-bid-scope/SKILL.md +64 -0
- contractor_bid-0.2.0/skills/division-22-plumbing-bid-scope/SKILL.md +65 -0
- contractor_bid-0.2.0/skills/division-23-hvac-bid-scope/SKILL.md +66 -0
- contractor_bid-0.2.0/skills/division-25-integrated-automation-bid-scope/SKILL.md +65 -0
- contractor_bid-0.2.0/skills/division-26-electrical-bid-scope/SKILL.md +66 -0
- contractor_bid-0.2.0/skills/division-27-communications-bid-scope/SKILL.md +65 -0
- contractor_bid-0.2.0/skills/division-28-electronic-safety-security-bid-scope/SKILL.md +66 -0
- contractor_bid-0.2.0/skills/division-31-earthwork-bid-scope/SKILL.md +66 -0
- contractor_bid-0.2.0/skills/division-32-exterior-improvements-bid-scope/SKILL.md +66 -0
- contractor_bid-0.2.0/skills/division-33-utilities-bid-scope/SKILL.md +65 -0
- contractor_bid-0.2.0/skills/drywall-framing-bid-scope/SKILL.md +62 -0
- contractor_bid-0.2.0/skills/electrical-bid-scope/SKILL.md +63 -0
- contractor_bid-0.2.0/skills/fences-gates-bid-scope/SKILL.md +64 -0
- contractor_bid-0.2.0/skills/hvac-bid-scope/SKILL.md +72 -0
- contractor_bid-0.2.0/skills/plumbing-bid-scope/SKILL.md +69 -0
- contractor_bid-0.2.0/skills/roofing-bid-scope/SKILL.md +71 -0
- contractor_bid-0.2.0/src/contractor_bid/__init__.py +5 -0
- contractor_bid-0.2.0/src/contractor_bid/__main__.py +4 -0
- contractor_bid-0.2.0/src/contractor_bid/cli.py +506 -0
- contractor_bid-0.2.0/src/contractor_bid/csi_starters.py +1269 -0
- contractor_bid-0.2.0/src/contractor_bid/doctor.py +100 -0
- contractor_bid-0.2.0/src/contractor_bid/learning.py +42 -0
- contractor_bid-0.2.0/src/contractor_bid/mcp_server.py +845 -0
- contractor_bid-0.2.0/src/contractor_bid/packets.py +326 -0
- contractor_bid-0.2.0/src/contractor_bid/profile.py +185 -0
- contractor_bid-0.2.0/src/contractor_bid/project.py +101 -0
- contractor_bid-0.2.0/src/contractor_bid/sendoff.py +76 -0
- contractor_bid-0.2.0/src/contractor_bid/tracker.py +382 -0
- contractor_bid-0.2.0/src/contractor_bid/triage.py +483 -0
- contractor_bid-0.2.0/src/contractor_bid/util.py +90 -0
- contractor_bid-0.2.0/src/contractor_bid/validate.py +251 -0
- contractor_bid-0.2.0/src/contractor_bid/workbook.py +328 -0
- contractor_bid-0.2.0/templates/00-scope-reference-index-template.md +45 -0
- contractor_bid-0.2.0/templates/02-proposal-letter-template.md +48 -0
- contractor_bid-0.2.0/templates/project-readme-template.md +38 -0
- contractor_bid-0.2.0/templates/review-pages-template.md +7 -0
- contractor_bid-0.2.0/templates/scope-pages-sources-template.json +19 -0
- contractor_bid-0.2.0/templates/takeoff-template.json +48 -0
|
@@ -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,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
|
+
[](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
|
+

|
|
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).
|