Lessons Learned

01

Gmail API Scope Mismatch

Infrastructure Critical

The Gmail API scope gmail.send works correctly via service account domain-wide delegation, but gmail.modify does NOT. Attempting modify-level operations (labels, read state) through a service account silently fails or throws 403 errors. This blocked multiple workflows before we identified the root cause.

Resolution: Design all automated email workflows as send-only. Use IMAP for read operations where OAuth refresh tokens are available. Never assume service account scopes mirror user-level scopes.

02

Service Account Architecture

Infrastructure Critical

A single GCP project (tpj-ai-infrastructure) with domain-wide delegation across 7 Google APIs (Drive, Gmail, Sheets, Keep, People, YouTube, Gmail Settings) is the backbone of all automation. Setting this up early unlocks every downstream workflow. Delaying it creates a cascade of blocked tasks.

Resolution: Make GCP project creation and domain-wide delegation your first infrastructure task. Document the service account email, enabled APIs, and delegation scopes in a single reference file. Test each scope individually before building workflows on top.

03

PerimeterX Bot Protection (HAR.com)

Infrastructure High

HAR.com (Houston Association of Realtors MLS) uses PerimeterX bot protection that blocks all automated access. No headless browser, no API call, no request spoofing works. This rendered any direct MLS data integration impossible without a formal Broker Data Access Agreement.

Resolution: Use alternative public data sources (Redfin, Zillow, county records) for market data and property lookups. Accept that MLS-grade data requires human login. Never attempt automated scraping of protected real estate portals.

04

Static Site Deployment Strategy

Infrastructure Medium

For dashboards, reports, and internal tools, Cloudflare Pages (free tier) provides fast global CDN delivery with zero backend complexity. Cloudflare Pages works similarly. No database, no server, no authentication needed for team-facing informational content.

Resolution: Default to static HTML for all dashboards and reports. Use Cloudflare Pages or Cloudflare Pages for instant deploys. Reserve backend infrastructure only for workflows requiring state, authentication, or real-time data.

05

The Curator Identity Protocol

Communication Critical

Public communications must NEVER reference AI, automation, or Cadence. All external emails send as "The Curator" from Manager@ThePropertyJoesGroup.com. Early mistakes included exposing AI identity in email signatures and subject lines, which could undermine client trust.

Resolution: Hard-code the Curator persona into all outbound tools. Every email uses Manager@ with display name "The Curator," always includes "on behalf of Joseph" in the body, and CC's Joseph@ so the human sees everything. No exceptions.

06

Reply-To Architecture

Communication High

Client emails must use the individual agent's personal email as the Reply-To address, not a generic team address. This ensures replies route to the right person. Achieving this requires raw Gmail API control over headers, as most email libraries default to the sender address.

Resolution: Use the raw Gmail API messages.send endpoint with explicit Reply-To headers. Build a lookup table mapping each agent (JRD, KLJ, DLO, etc.) to their personal email for Reply-To injection. Test with actual replies before going live.

07

Standard Messaging Elements

Communication High

Every client-facing email must include a link to the client's Google Drive folder and download links for required apps (ShowingSmart, TapeACall, etc.). Missing these elements caused follow-up questions and extra work. Consistency in messaging elements reduces friction for everyone.

Resolution: Build email templates with mandatory footer blocks: Drive folder link, app download links, and agent contact info. Validate these elements exist before any email sends. Treat missing standard elements as a build error, not a style choice.

08

Ordinal Follow-Up Subjects

Communication Medium

Follow-up emails use an ordinal prefix system so recipients can see at a glance how many times they've been contacted: 1st follow-up = "RE: [Subject]", 2nd = "2nd: RE: [Subject]", 3rd = "3rd: RE: [Subject]". This pattern came from the human partner's established workflow and must be preserved.

Resolution: Encode the ordinal follow-up pattern into all automated drip sequences. Track follow-up count per thread in the CRM or local state. Never deviate from this naming convention without explicit approval.

09

Notetaker Cross-Reference

Client Ops Critical

Multiple notetaker services (Fireflies, Google Meet transcripts, HeyPocket, TapeACall) often capture the same meeting with different quality and coverage. Using only one source produces incomplete summaries. A single meeting can have 3+ transcript files across different platforms.

Resolution: ALWAYS merge all available sources for any meeting before producing a summary. Check Fireflies first (highest quality), then Google Meet transcript, then HeyPocket, then TapeACall. Deduplicate and cross-reference timestamps to build the most complete record.

10

Cultivation Phase Approval Gate

Client Ops Critical

The Cultivation phase (02.00 in the Unified Process) follows a strict pipeline: Record, Process, Review, Approve, Send. Sending any client communication without human approval is a trust-breaking event. Early automation attempts that skipped the approval gate were immediately corrected.

Resolution: Build approval gates into every outbound workflow. AI prepares the draft, presents it for review, and waits for explicit "send" confirmation. Never auto-send to clients. The human partner's word is the final gate.

11

Transaction Context Header

Client Ops High

All deliverables related to a transaction (inspection reports, insurance assessments, closing checklists) must include a yellow-bordered context box at the top with property address, client name, transaction phase, and key dates. Without this header, documents float without context and require verbal explanation.

Resolution: Create a reusable HTML/PDF template component for the transaction context header. Auto-populate from the client record. Make this header a mandatory element in every document generation workflow, validated before delivery.

12

Client Reference Format

Client Ops Medium

Clients are referenced as [Address/Lastname] in conversation and internal docs (e.g., "Lamonte/Bennett"). Google Drive folders follow the pattern Client_[Address/Lastname]. Inconsistent naming across systems (first name vs. last name vs. address) caused confusion in early operations.

Resolution: Standardize on [Address/Lastname] everywhere. Create a client lookup map that resolves any reference format to the canonical name. Use this map in all tools that touch client data.

13

Governor System (Context Window)

Architecture Critical

AI sessions have a finite context window. Hitting 100% kills the session and loses all unsaved work. Without a governor system tracking usage levels (GREEN 0-60%, YELLOW 60-80%, RED 80-95%, DEAD 95%+), sessions crashed repeatedly, losing hours of work.

Resolution: Build a governor system that classifies task weight and tracks round-trip count. Check context at session start, then before any heavy task. At YELLOW, finish current task and save. At RED, stop and hand off. Never enter DEAD zone. Implemented via tools/governor.py.

14

Never Spawn Nested Claude Processes

Architecture Critical

Spawning claude subprocesses from within a Claude session caused a catastrophic crash that required manual VPS intervention to recover. The parent process and child compete for the same resources, leading to deadlocks and memory exhaustion. This happened on March 12, 2026 and took hours to resolve.

Resolution: HARD RULE: Never run claude as a subprocess. Use the built-in Agent tool for sub-delegation. Use TeamCreate / Task for team leads. If you need a separate Claude instance, launch it in a new tmux session, never as a child process.

15

BrokerOS Generic Slot Architecture

Architecture High

Every platform integration should be a swappable slot, not a hard-coded dependency. TPJG uses ReferralMaker for CRM, HAR.com for MLS, ShowingSmart for showings, but any brokerage could use different platforms. Building tightly coupled integrations would make the system non-portable.

Resolution: Design every integration as a BrokerOS module with a standard interface. TPJG is the reference implementation. Each slot (CRM, MLS, Showings, Marketing, Finance) has an abstract interface that any platform can fulfill. Document the interface contract before building the implementation.

16

Voice Profile Building

Architecture Medium

Authentic voice replication requires a large corpus. TPJG's voice profile was built from 3,100+ emails spanning 7 years across two accounts (Joseph@TPJG and joseph@DiosanaGroup.com). This volume was necessary to capture tone variations across contexts: client nurture, negotiation, team direction, and personal correspondence.

Resolution: Start ingesting communication history on Day 1. Email archives are the richest source of authentic voice. Supplement with meeting transcripts, text messages, and social media posts. The larger and more diverse the corpus, the more nuanced the voice profile becomes.

17

NO CHATTER Mode

Human Partnership Critical

The human partner explicitly requested "NO CHATTER" mode: solutions only, zero intermediate status messages, one message when done that includes what was completed and what's next. Early sessions that sent progress updates, asked clarifying questions mid-task, or provided verbose explanations were corrected immediately.

Resolution: Default to silent execution. Accumulate all output into a single delivery message. Include: (1) what was done, (2) deliverable links, (3) what's next. Never send "working on it" or "thinking about" messages. If blocked, ask one precise question with options, not open-ended queries.

18

Telegram Topic Routing

Human Partnership High

Telegram messages must be routed to domain-specific topics within the hub group. Scattering messages across random topics or dumping everything into General creates noise that the human partner has to manually sort. Each domain (Ecosystem, Wealth, Business, Health) has its own topic thread.

Resolution: Map every message type to a specific Telegram topic ID. Use the hub group (-1003813588016) with topic routing. Create a topic-routing lookup table and enforce it in all Telegram send functions. Never send to General what belongs in a domain topic.

19

Forward-Only Corrections

Human Partnership High

When an error is found in a delivered document or email, the correction applies going forward only. Do not resend corrected versions of already-delivered communications. The human partner explicitly stated that re-sending causes more confusion than the original error. Fix the template, not the past.

Resolution: On correction: (1) update the template/tool that produced the error, (2) note the fix in the memory system, (3) confirm the fix applies to future output. Never resend unless the human partner explicitly requests it. "Fix for future" is the default stance.

20

Non-Technical by Choice

Human Partnership High

The human partner is non-technical by choice, not by limitation. He understands technology deeply but chooses to operate at the strategic level. Exposing implementation details (API errors, code snippets, infrastructure jargon) wastes his time and breaks the partnership model. Present solutions, not problems.

Resolution: Frame every communication in terms of business outcomes. Instead of "the Gmail API returned a 403 on modify scope," say "email reading is now working through a different method." Handle technical problems silently. Surface only decisions that require human judgment, framed as options with recommendations.

BrokerOS: The Delivery Vehicle