Colony — Progressive Product Requirements Document

---

PRD Metadata

---

v0.1 Spark — Problem & Outcomes

Problem Statement

ZoomProp's go-to-market motion is fragmented across disconnected point solutions: a CRM that doesn't talk to the outbound tool, a recording platform whose signals never reach the pipeline, content that is produced without attribution to revenue, and onboarding assets that are assembled manually after every closed deal. Founders and GTM leads spend three to four hours per day context-switching between these surfaces — Pipedrive, a LinkedIn outreach tool, a meeting recorder, a content calendar, and a spreadsheet — instead of executing. There is no single source of truth, no memory layer that accumulates institutional knowledge, and no way to command the entire GTM stack in plain English.

The deeper problem: the raw capability to automate every stage of the GTM loop (prospect discovery, qualification, personalised outreach, meeting intelligence, post-call nurture, content production, onboarding, and analytics) already exists in the form of LLMs and specialist APIs, but it is not orchestrated into a coherent product. Each capability lives in a silo, requires separate configuration, and produces output that no other tool can consume.

Desired Outcomes

Constraints

• Single-tenant per deployment at Phase 1. Clerk organizations map 1:1 to a Colony deployment; multi-org switching is hardened in Phase 2 (docs/phase2/action_plans/27_org_switcher_hardening.md).
• GCP-only infrastructure. Cloud Run, Cloud SQL (colony-39989:…:colony), Cloud Storage (gs://colony-assets), GCP Secret Manager, and KMS are the mandated primitives. No AWS or Azure resources.
• Human-in-the-loop approval gates are non-negotiable. Every outbound message and every prospect candidate batch must pass through an approval queue before being sent. Circuit breakers enforce per-org send limits (docs/phase1/action_plans/22_circuit_breakers.md, docs/phase2/action_plans/11_circuit_breakers_phase2.md).
• No cold start on LLM calls without context. Every message, content piece, and brief must pull exemplars from the Knowledge Core via pgvector before generation.
• RBAC is enforced at the API layer. Three Clerk roles gate every action; the GitHub Actions workflow .github/workflows/rbac-check.yml runs on every PR.
• Two-tier secret architecture is fixed. Platform-level secrets live in GCP Secret Manager; per-org credentials (Pipedrive, Unipile, etc.) live in the KMS-encrypted api_keys table (Colony Vault).

---

v0.2 Market Definition — ICP & Segments

Ideal Customer Profile

Colony is built first and specifically for the ZoomProp GTM team — a PropTech founder-led organisation running a high-velocity B2B outbound motion targeting institutional real estate buyers, fund analysts, and property operators. The generalised ICP, should Colony be productised beyond ZoomProp, is a seed-to-Series-A B2B SaaS or PropTech company with 2–10 people on the GTM team, an existing Pipedrive CRM, and a need to run personalised outbound at volume without hiring an SDR team.

Segment Table

"Not For"

• Enterprise sales organisations with existing Salesforce deployments and dedicated RevOps teams of 5+. Colony does not integrate with Salesforce and does not attempt to replace a mature CRM stack.
• Outbound agencies managing multiple client accounts. Colony's per-org Clerk architecture and vault model are not designed for an agency reseller model.
• Consumer or B2C businesses. Every agent, prompt, and ICP-scoring heuristic in Colony is calibrated for B2B deal cycles.
• Teams unwilling to maintain human approval gates. Colony's design philosophy requires founder review of outbound messages; fully autonomous send is not supported and is blocked by circuit breakers.

---

v0.3 Commercial Model — Pricing & Positioning

Positioning

Colony is not a CRM. It is not an outbound sequencer. It is not a meeting recorder. It is the command plane that makes all three — and six other GTM workflows — work as a single system. The competitive frame is: "What if your entire GTM stack had one interface, one memory layer, and one agent brain?" The product is positioned as infrastructure for founder-led GTM, not a SaaS tool with a features checklist.

Monetisation

At the current stage, Colony is an internal platform for ZoomProp with no external pricing. The commercial model described here applies to the productisation path.

Moat Thesis

Colony's durable differentiation is the Knowledge Core — a pgvector-backed, 10-domain institutional memory that compounds with every message sent, every recording ingested, and every case study produced. Competitors can replicate the outbound sequencer or the chat interface. They cannot replicate 12–24 months of accumulated GTM signals, winning message exemplars, ICP qualification history, and post-call insights that are embedded into every generation call Colony makes. The moat is the data flywheel, not the feature set.

A secondary moat is the two-tier secret architecture and per-org circuit breaker model, which allows Colony to safely hand the keys of a production GTM stack to a non-technical founder without risk of runaway sends or credential exposure. This compliance posture will matter increasingly as email deliverability regulations tighten (docs/phase2/action_plans/19_email_deliverability_and_warmup.md).

---

v0.4 User Journeys

UJ-001: Daily GTM Command — Morning Brief to First Action

Actor: Founder / GTM Lead (Clerk role: owner) Entry Point: Email inbox (Resend delivery) or /overview route Trigger: Scheduled daily brief job fires each morning

1. Founder opens the daily brief email. It contains: pipeline today (deals by stage), alerts (deals at risk, HOT reply queue depth), yesterday's output (messages sent, content published, recordings processed).
2. Founder navigates to /overview. The GTM Orchestrator chat interface is pre-loaded with the same brief as context.
3. Founder types: "There are two HOT replies in the queue — draft responses and get them ready for my review."
4. The orchestrator streams a multi-turn tool loop: fetches HOT reply queue → retrieves conversation history from api_keys-vaulted Unipile → pulls message exemplars from Knowledge Core via pgvector → generates two personalised replies.
5. Replies surface in the approval queue. Founder reviews, edits one, approves both.
6. Unipile sends messages. Circuit breaker decrements the per-org daily send counter.

Success Metric: Full loop completes in < 8 minutes from brief open.

---

UJ-002: Prospect Discovery Campaign

Actor: Founder (Clerk role: owner) Entry Point: /overview chat interface Trigger: Founder identifies a new ICP segment to target

1. Founder types: "Find 20 European fund analysts at firms with AUM > €500M and draft signal-led outreach for each."
2. GTM Orchestrator dispatches the Campaign Orchestrator via Inngest event.
3. Campaign Orchestrator fans out to the Prospect Agent, which queries: Pipedrive LeadBooster scraper (docs/phase2/action_plans/02_pipedrive_leadbooster_scraper.md), Google Places (docs/phase2/action_plans/03_google_places_integration.md), SerpAPI (docs/phase2/action_plans/04_serpapi_integration.md), Unipile LinkedIn search (docs/phase2/action_plans/06_unipile_search_extension.md), and public data adapters (docs/phase2/action_plans/05_public_data_adapters.md).
4. The Matching Algorithm (docs/phase2/action_plans/08_matching_algorithm.md) scores each candidate against the ICP definition. Anti-ICP hard pre-filter (docs/phase2/action_plans/16_anti_icp_hard_prefilter.md) eliminates disqualifying signals before scoring.
5. Candidates surface in the Candidate Approval Queue (docs/phase2/action_plans/09_candidate_approval_queue.md). Founder reviews the shortlist; rejects 3, approves 17.
6. Approved candidates are passed to the Qualification Agent, which enriches each with LinkedIn activity signals, company news (SerpAPI), and any existing CRM history.
7. Message Generator Agent selects the signal-led angle (one of 5: signal, pain, referral, pattern-break, insight) and generates personalised messages for each contact, pulling exemplars from Knowledge Core.
8. Messages enter the approval queue. Founder batch-approves. Outbound Sequence Engine enrols each contact into a T1 sequence.

Success Metric: 17 approved, personalised messages queued for send within 90 minutes of the initial command.

---

UJ-003: Recording Intelligence — Meeting to CRM

Actor: System (automated), reviewed by GTM Lead Entry Point: Google Drive folder watched by Recording Intelligence Agent Trigger: Gemini Meet Notes file appears in the configured Drive folder

1. A new meeting recording summary is written to Google Drive by Gemini Meet Notes.
2. The Recording Intelligence Agent (docs/phase1/action_plans/14_recording_intelligence_agent.md) detects the new file.
3. Agent extracts structured signals: deal stage indicators, objections raised, next steps committed, stakeholder sentiment, buying signals.
4. Signals are written to the corresponding Pipedrive deal fields via bi-sync. The deal's ICP score is recalculated.
5. Extracted insights are embedded and upserted into the Knowledge Core (domain: recording_signals).
6. Post-Call Agent (docs/phase1/action_plans/15_post_call_agent.md) generates a follow-up email draft, a humanised post-call summary (docs/phase2/action_plans/18_humanized_post_call_writer.md), and updates the deal's next-step task in Pipedrive.
7. The draft follow-up appears in the approval queue for the GTM Lead.

Success Metric: Zero manual CRM updates required after a recorded meeting. Signal-to-CRM latency < 15 minutes.

---

UJ-004: Closed-Won → Deployment Kit Generation

Actor: System (automated), reviewed by Founder Entry Point: Pipedrive deal stage change to "Closed-Won" (bi-sync event) Trigger: deal.stage_changed event consumed by Inngest

1. Bi-sync detects the stage change and fires an Inngest event.
2. Onboarding Agent (docs/phase1/action_plans/17_onboarding_agent.md) receives the event.
3. Agent reads the full deal record, contact history, and meeting recordings from the Knowledge Core.
4. Agent generates 8 assets: pitch deck, one-pager, case-study shortlist, pricing reference, rollout calendar, stakeholder map, risk register, KPI dashboard.
5. Assets are stored in GCS (gs://colony-assets) with CMEK encryption and signed URLs.
6. A deployment_kit record is written to Postgres linking all 8 asset URLs to the deal.
7. Founder receives a Resend email with links to all 8 assets and a summary of the onboarding recommended path.

Success Metric: All 8 assets generated and delivered within 4 hours of Closed-Won.

---

UJ-005: Content Pipeline — Pillar to Pipeline Attribution

Actor: Content Agent (automated), reviewed by GTM Lead Entry Point: Scheduled Inngest job or manual command via /overview Trigger: Weekly content cadence or explicit "create content" command

1. Content Agent (docs/phase1/action_plans/16_content_agent.md) selects the active content pillar from the 6-pillar framework.
2. Agent retrieves relevant exemplars from Knowledge Core (domain: content_exemplars) and recent pipeline signals (deal stage distribution, common objections from recording signals).
3. Agent drafts the content piece (LinkedIn post, newsletter section, or case study draft) with pipeline-influence hooks embedded.
4. Draft appears in the approval queue. GTM Lead reviews, edits, approves.
5. On approval, content is published via the configured channel. Attribution metadata is written to the content_pieces table, linking the piece to the active deals it influences.
6. Analytics Agent tracks downstream pipeline movement correlated with content publish date.

Success Metric: Every published content piece has an attribution record in content_pieces. Pipeline influence is visible in the daily brief within 48 hours.

---

UJ-006: Knowledge Core — Curation and Retrieval

Actor: Founder / GTM Lead (Clerk role: owner or member) Entry Point: Knowledge Core Editor (docs/phase1/action_plans/24_knowledge_core_editor.md) Trigger: Manual curation or automated ingestion from recording/content agents

1. GTM Lead opens the Knowledge Core editor surface.
2. Lead reviews recently auto-ingested entries (from recording signals, approved messages, published content) across 10 domains.
3. Lead promotes a winning message variant to "exemplar" status, adding a tag and a quality note.
4. The entry is re-embedded with pgvector (1536-dimension OpenAI embeddings) and upserted.
5. All subsequent Message Generator calls for the relevant ICP segment retrieve this exemplar as a top-k result (cosine similarity retrieval).

Success Metric: Exemplar retrieval hit rate ≥ 82% on a monthly benchmark query run.

---

v0.5 Red Team Review

Risk Register

---

v0.6 Architecture

System Overview

Colony is a Next.js 16 / React 19 application deployed to GCP Cloud Run (infrastructure/gcp/cloud-run-runner.tf), backed by Cloud SQL Postgres 16 (infrastructure/gcp/cloud-sql.tf) with the pgvector (1536-dimension) and pgcrypto extensions initialised in infrastructure/postgres/init/02-extensions.sql. Static and generated assets are stored in GCS (gs://colony-assets, defined in infrastructure/gcp/storage.tf) with CMEK encryption and signed URL access.

Authentication and multi-tenancy are managed by Clerk, with Svix webhooks providing real-time organisation and user sync into the Postgres users and organisations tables. Three RBAC roles (owner, member, viewer) are enforced at the Next.js App Router API layer and validated in CI via .github/workflows/rbac-check.yml.

Agent execution is driven by Inngest durable functions, which provide event-sourced, retry-capable orchestration for all long-running agent workflows. The GTM Orchestrator and Campaign Orchestrator are multi-turn Inngest functions; specialist agents are dispatched as child functions.

TECH References

API Surface

Database Model (Inferred)

---

v0.7 Build Execution

EPIC Backlog

EPIC-001: Infrastructure & Data Foundation (Phase 1, Wave 0)

Reference: docs/phase1/action_plans/01_infrastructure_and_database.md

• Provision Cloud SQL Postgres 16 via infrastructure/gcp/cloud-sql.tf
• Run infrastructure/postgres/init/01-multiple-dbs.sh and 02-extensions.sql to enable pgvector and pgcrypto
• Bootstrap GCS bucket gs://colony-assets with CMEK (infrastructure/gcp/storage.tf)
• Configure GCP Secret Manager secrets (infrastructure/gcp/secrets.tf)
• Deploy Terraform workspace (infrastructure/gcp/main.tf); lock file at .terraform.lock.hcl
• Validate Cloud Run service account IAM bindings (infrastructure/gcp/iam-runner.tf)

EPIC-002: Auth, RBAC & Multi-Tenancy (Phase 1)

Reference: docs/phase1/action_plans/02_clerk_auth_and_rbac.md

• Integrate Clerk with Next.js App Router
• Configure Svix webhook for organization.* and user.* events → Postgres sync (DBT-001, DBT-002)