Instructions for building CaseyOS, a GTM command center that operates like a proactive Chief of Staff. Includes architecture patterns, database conventions, CSRF protection, command queue system, and deployment workflows.
Transform GitHub Copilot into an expert guide for building **CaseyOS**, a GTM command center that proactively surfaces priorities, automates sales workflows, and acts as a Chief of Staff.
This skill configures Copilot with deep knowledge of the CaseyOS architecture, conventions, and development patterns. It will help you:
**CaseyOS** is a GTM command center deployed at `https://web-production-a6ccf.up.railway.app`. It's NOT a CRM—it's a decision engine + execution system that:
1. Ingests form leads from HubSpot webhooks
2. Researches prospects via Gmail/Drive search
3. Generates personalized email drafts using AI
4. Surfaces prioritized actions in a Command Queue ("Today's Moves")
5. Auto-approves and sends high-confidence emails via Gmail API
**Tech Stack:** FastAPI, PostgreSQL (async), Redis, Celery, SQLAlchemy, OpenAI/Gemini, Railway
```
FastAPI App (120+ routes)
↓
Command Queue (APS-scored priority actions)
↓
Orchestrator Layer (Jarvis master router, Deep Research, Content Engine)
↓
Connectors (Gmail, HubSpot, Drive, LLM)
↓
Data Layer (PostgreSQL async + Redis + Alembic migrations)
```
**ALWAYS use this pattern for database operations:**
```python
from src.db import get_session
async def my_route():
async with get_session() as session:
result = await session.execute(select(Model))
return result.scalars().all()
```
**RULES:**
**Pre-commit hook blocks:**
All agents extend `BaseAgent`:
```python
from src.agents.base import BaseAgent
class MyAgent(BaseAgent):
def __init__(self):
super().__init__(name="MyAgent", description="Does X")
async def validate_input(self, context: Dict) -> bool:
return "required_field" in context
async def execute(self, context: Dict) -> Dict:
# Agent logic here
return {"result": "success"}
```
**Auto-injection pattern:** All HTML files include `csrf-helper.js` which automatically injects `X-CSRF-Token` headers into fetch() calls.
**Whitelist:** CSRF skipped for:
**Testing CSRF:**
```bash
curl -I $BASE/health | grep X-CSRF-Token
curl -X POST $BASE/api/command-queue/test/accept
curl -X POST $BASE/api/command-queue/test/accept \
-H "X-CSRF-Token: <token>"
```
APS formula (0-100):
**API:**
```bash
curl $BASE/api/command-queue/today # Today's Moves ranked by APS
curl -X POST $BASE/api/command-queue/<id>/accept \
-H "X-Admin-Token: $ADMIN_PASSWORD" \
-H "X-CSRF-Token: $CSRF"
```
**Required:**
**Safety Flags:**
```bash
make docker-up # Start postgres + redis + api (hot reload)
make test # Run all tests
make lint # ruff check + pyright
make secrets-check # Validate required env vars
make smoke-formlead # E2E test with mocked connectors
make auth-google # OAuth flow for Gmail/Drive/Calendar
```
1. HubSpot form webhook → `/api/webhooks/hubspot`
2. `FormleadOrchestrator.process_formlead()` runs 11 steps:
- Validate payload, resolve HubSpot contact/company
- Search Gmail for threads, hunt Drive for assets
- Research prospect, generate meeting slots
- Draft personalized email with voice profile
- Calculate ICP fit score, store in PostgreSQL
3. Draft enters `DraftQueue` → Operator UI for approval
4. Auto-approval engine evaluates; high-confidence drafts auto-send via Gmail API
1. **Email sending** controlled by feature flags
2. **Auto-approval** rules engine with confidence scoring
3. **Rate limiting** 2/week, 20/day per contact
4. **Webhook security** HMAC-SHA256 validation
5. **CSRF protection** 99.6% coverage
6. **Admin auth** `X-Admin-Token` header required
7. **Audit trail** all actions logged
8. **Kill switch** `/api/admin/emergency-stop`
1. **Atomic Tasks:** One intent per commit, small diffs
2. **Validation First:** Define success criteria before coding
3. **Demoable Sprints:** Every sprint ships working end-to-end
4. **No Noise, Only Signal:** If not actionable, doesn't belong in UI
5. **Closed-Loop Learning:** Record outcomes, feed back into scoring
```python
from src.agents.base import BaseAgent
from src.db import get_session
from sqlalchemy import select
class ProspectResearchAgent(BaseAgent):
def __init__(self):
super().__init__(
name="ProspectResearchAgent",
description="Researches prospects via Gmail and Drive"
)
async def validate_input(self, context: dict) -> bool:
return "email" in context and "company" in context
async def execute(self, context: dict) -> dict:
email = context["email"]
# Use proper session pattern
async with get_session() as session:
result = await session.execute(
select(Contact).where(Contact.email == email)
)
contact = result.scalar_one_or_none()
# Research logic here
return {"contact": contact, "insights": [...]}
```
```python
from fastapi import APIRouter, Depends, HTTPException
from src.db import get_db
from src.security.admin_auth import verify_admin_token
from sqlalchemy.ext.asyncio import AsyncSession
router = APIRouter(prefix="/api/admin")
@router.post("/items/{item_id}/approve")
async def approve_item(
item_id: str,
session: AsyncSession = Depends(get_db),
admin_token: str = Depends(verify_admin_token) # CSRF auto-injected
):
result = await session.execute(select(Item).where(Item.id == item_id))
item = result.scalar_one_or_none()
if not item:
raise HTTPException(status_code=404, detail="Item not found")
item.approved = True
await session.commit()
return {"status": "approved", "item_id": item_id}
```
```python
from src.models.command_queue import CommandQueueItem
item = CommandQueueItem(
action_type="send_email",
title="Follow up with Acme Corp",
description="High-value prospect, event tomorrow",
metadata={
"email": "[email protected]",
"deal_value": 50000,
"deadline": "2024-12-15"
},
# APS will be calculated automatically
revenue_impact=0.9, # High deal value
urgency=0.95, # Event tomorrow
effort=0.2, # Quick email
strategic_value=0.8 # Strong ICP fit
)
async with get_session() as session:
session.add(item)
await session.commit()
```
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/github-copilot-sales-agent-instructions/raw