buildertrend（buildertrend 搜索）

Buildertrend Skill — {{company_name}}

Overview

Buildertrend is {{company_name}}'s project management platform. No API exists — all automation goes through the browser via OpenClaw's Chrome Extension Relay.

New here? See Setup & Configuration below to get started.

How It Works

1. the user logs into Buildertrend in Chrome
2. the user clicks the OpenClaw Browser Relay toolbar icon on the Buildertrend tab (badge goes ON)
3. the agent uses browser tool with profile="chrome" to control the tab
4. Workflow: snapshot → read → act → verify

Critical Rules

Before ANY Action

1. browser snapshot — confirm you're on the right page
2. Check for login screen — if logged out, STOP and ask the user to re-authenticate
3. Check for loading spinners — wait until page is fully loaded
4. Identify the correct element refs before clicking

During Actions

• One click at a time — snapshot after each action to verify result
• Never rush — add reasonable pauses between actions
• Read before writing — always capture current state before modifying
• Modal awareness — check if a modal is open before trying to interact with the page behind it

On Errors

• Screenshot immediately
• Report what happened + what you were trying to do
• Do NOT retry blindly — ask for guidance
• Save error screenshots to memory/bt-errors/

Navigation Patterns

*(To be populated during Phase 1 discovery)*

Module Reference

See STRATEGY.md for complete module inventory and priority rankings. See buildertrend-map.json for UI element mappings (once discovered).

Playbooks

See playbooks/ directory for step-by-step automation workflows. See playbooks/README.md for the full index with cross-references.

Available Playbooks (43 Total):

Sales & Pre-Construction (6):

Client & Contact Management (4):

Project Management (9):

Financial (12):

Labor & Time (1):

Setup & Administration (7):

Integrations (1):

Closeout (2):

Mobile (1):

Playbook Pattern (All Workflows):

1. Trigger → user command, scheduled event, or external input
2. Identify → Which project? (inline buttons)
3. Gather → Collect details (guided prompts or freeform)
4. Suggest → Smart defaults (cost codes, vendors, amounts, tags)
5. Review → Present summary with Create / Edit / Cancel buttons
6. Execute → Browser Relay actions in Buildertrend (snapshot → act → verify)
7. Post-action → Log it, update Reminders, notify other agents, check QBO sync

See playbooks/README.md for the full index and detailed documentation.

References

• bt-ui-patterns.md — Browser Relay interaction patterns for all BT forms: PO, Schedule, Change Order, Lead, combobox dropdowns, modals, grids, navigation (16 sections, 432 lines)
• knowledge-base.md — Complete BT module reference (2,349 lines). ⚠️ Do NOT load the entire file per task — it will consume significant context window. Load only the relevant section for the current workflow.
• qbo-sync-guide.md — QuickBooks Online integration reference
• workflows.md — Official BT workflow procedures
• knowledge-base.md — Complete BT module reference (2,349 lines). ⚠️ Do NOT load this entire file per task — search or load only the relevant section for the module you're working with. Loading the full file consumes significant context window.
• qbo-sync-guide.md — QuickBooks Online integration reference
• workflows.md — Official BT workflow procedures

Session Management

• Buildertrend sessions expire — always verify login state before starting a workflow
• If session expired: notify the user, do NOT attempt to enter credentials
• the user handles all login/authentication — the agent never touches credentials

Data Extraction

When pulling data from Buildertrend (budgets, schedules, etc.):

1. Snapshot the page
2. Parse the aria/role tree for structured data
3. Format into clean output (JSON or markdown table)
4. Store in appropriate memory file or pass to requesting agent

Integration

• Budget data → bookkeeper agent (QBO reconciliation)
• PO data → procurement agent (procurement tracking)
• Contact data → CRM agent (CRM enrichment)
• Schedule/CO/Daily logs → the agent (project reporting)
• Documents → Google Drive (archive)

Setup & Configuration

Prerequisites

• OpenClaw v2026.2.20 or later
• OpenClaw Browser Relay Chrome extension installed
• Buildertrend account (any plan with the modules you want to automate)
• Chrome browser — the user must be logged into BT in Chrome

Step 1: Install the Skill

Copy the buildertrend/ folder into your OpenClaw workspace under SKILLS/:

~/.openclaw/workspace/SKILLS/buildertrend/

Step 2: Configure Placeholders

This skill uses {{placeholders}} throughout. Find and replace these with your company's values across all files:

Quick replace (run from the skill root):

find . -name "*.md" -exec sed -i '' 's/{{company_name}}/Your Company/g' {} +

Repeat for each placeholder with your values.

Step 3: Customize Project Picker Buttons

Many playbooks include inline button tables for project selection. Replace the example projects with your actual projects:

Before:

| 🏗️ Project Alpha | `primary` | `bt_co_project_1` |
| 🏗️ Project Alpha | `primary` | `bt_co_project_3` |

After:

| 🏗️ 123 Main St Office Buildout | `primary` | `bt_co_project_MAIN` |
| 🏗️ 456 Oak Ave Renovation | `primary` | `bt_co_project_OAK` |

Step 4: Set Up Browser Relay

1. Install the OpenClaw Browser Relay Chrome extension
2. Log into Buildertrend in Chrome
3. Click the Browser Relay toolbar icon on the BT tab (badge turns ON)
4. The agent can now control the tab via browser tool with profile="chrome"

Step 5: Test on a Test Project

⚠️ Do NOT test on live projects. Create a test job in Buildertrend first:

1. Create a job called "Test Project" in BT
2. Run a simple playbook (e.g., create-daily-log.md)
3. Verify the agent can snapshot, navigate, and interact correctly
4. Once confirmed, move to live projects

Multi-Agent Setup (Optional)

Running a single agent? This skill works fully with one agent. You'll see ~75 references to specialized agents (bookkeeper agent, receipt agent, procurement agent, CRM agent) across the playbooks — ignore these. When a playbook says "Notify bookkeeper agent," just skip that step or handle it yourself. No multi-agent setup required.

If you DO run multiple agents, configure their workspaces:

• Replace {{bookkeeper_workspace}} with your bookkeeper agent's workspace path
• Replace {{receipt_agent_workspace}} with your receipt agent's workspace path
• Replace {{procurement_agent_workspace}} with your procurement agent's workspace path
• Update the Integration section above with your agent names

Jurisdiction Configuration

Tax rates, retainage rules, and lien waiver requirements are configured with {{placeholders}}. Adjust these to match your local jurisdiction:

• Tax rate — set {{tax_rate}} to your combined rate
• Retainage — review playbooks/retainage-management.md for jurisdiction-specific rules
• Lien waivers — review playbooks/lien-waiver-tracking.md for local compliance requirements