# Builder Agent Profile

> Everything needed to operate Claude Code autonomously on the RateRight v2 codebase.
> Last updated: 2026-02-07

> ⚡ **READ FIRST:** Check `memory/agents/builder-updates.md` for latest overnight work and context from Rivet.

> 🔴 **ALL CODING VIA CLAUDE CODE ONLY.** Do NOT use Kimi sub-agents for code changes — they lack codebase context and introduce bugs. Use Claude Code v2.1.34 with `--dangerously-skip-permissions` for ALL code work. Claude Code can spawn its own Agent Teams for parallel coding tasks. Kimi agents are for research/planning/writing ONLY.

---

## 1. Claude Code on VPS — Setup & Auth

### Access
- **User:** `ccuser` (NEVER run as root)
- **Binary:** `/home/ccuser/.local/bin/claude`
- **Version:** 2.1.34
- **Auth:** OAuth tokens at `/home/ccuser/.claude/.credentials.json`
  - Subscription: **Claude Max** (20x rate limit tier)
  - Scopes: `user:inference`, `user:mcp_servers`, `user:profile`, `user:sessions:claude_code`
- **Config dir:** `/home/ccuser/.claude/`
- **MCP servers:** Notion (via npx @notionhq/notion-mcp-server)

### How to Run

```bash
# Switch to ccuser first
su - ccuser

# Interactive session in project dir
cd /home/ccuser/rateright-v2 && claude

# Non-interactive one-shot (for piping / automation)
# ALWAYS use --dangerously-skip-permissions for non-interactive runs
cd /home/ccuser/rateright-v2 && claude --dangerously-skip-permissions -p "Your prompt here"

# Continue last conversation
claude -c

# Resume specific session
claude -r <session-id>

# With specific model
claude --model sonnet "Your prompt"
claude --model opus "Your prompt"

# Skip all permission checks (sandboxed environments only)
claude --dangerously-skip-permissions -p "Your prompt"

# Print mode with JSON output
claude -p --output-format json "Your prompt"

# Streaming JSON output
claude -p --output-format stream-json "Your prompt"

# With budget limit
claude -p --max-budget-usd 5.00 "Your prompt"

# Plan mode (propose changes, don't execute)
claude --permission-mode plan -p "Your prompt"
```

### Spawning from Clawdbot (the coding-agent skill)

**CRITICAL: Always use `pty:true`** — Claude Code is an interactive terminal app.

```bash
# One-shot task
exec pty:true workdir:/home/ccuser/rateright-v2 command:"su - ccuser -c 'cd /home/ccuser/rateright-v2 && claude -p \"Your prompt\"'"

# Background long-running task
exec pty:true background:true workdir:/home/ccuser/rateright-v2 command:"su - ccuser -c 'cd /home/ccuser/rateright-v2 && claude -p \"Your prompt\"'"

# Monitor background sessions
process action:log sessionId:XXX
process action:poll sessionId:XXX
process action:kill sessionId:XXX
```

### Auto-Notify on Completion

Append this to prompts for background tasks so Clawdbot gets notified immediately:

```
When completely finished, run: clawdbot gateway wake --text "Done: [summary]" --mode now
```

### Pre-Allowed Permissions (settings.local.json)

Claude Code already has pre-approved permissions for:
- `git add`, `git commit`, `git push`, `git checkout`, `git reset`, `git rebase`
- `npm install`, `npm run build`
- `node`, `ls`, `grep`, `curl`, `echo`, `chmod`
- `npx playwright test`

---

## 2. GitHub CLI (gh) — Useful Commands

### Auth Status
- Logged in as: `mcloughlinmichaelr-debug`
- Token scopes: `read:org`, `repo`
- Protocol: HTTPS

### Key Commands

```bash
# Repository
gh repo view RateRight-PTY-LTD/the-50-dollar-app
gh repo clone RateRight-PTY-LTD/the-50-dollar-app

# Issues
gh issue list
gh issue create --title "Bug: ..." --body "..."
gh issue close <number>

# Pull Requests
gh pr create --title "feat: ..." --body "..." --base main
gh pr list
gh pr view <number>
gh pr checkout <number>
gh pr merge <number> --squash
gh pr comment <number> --body "..."

# Code Review
gh pr diff <number>
gh pr review <number> --approve
gh pr review <number> --request-changes --body "..."

# Workflow / Actions
gh run list
gh run view <id>
gh run watch <id>

# Releases
gh release create v1.0.0 --title "v1.0.0" --notes "..."

# API (raw)
gh api repos/RateRight-PTY-LTD/the-50-dollar-app
gh api repos/RateRight-PTY-LTD/the-50-dollar-app/issues
```

---

## 3. Codebase Structure — /home/ccuser/rateright-v2

### Repository
- **GitHub:** `RateRight-PTY-LTD/the-50-dollar-app` (private)
- **Branch:** `main` (only branch)
- **Remote:** `origin` → `https://github.com/RateRight-PTY-LTD/the-50-dollar-app.git`

### Tech Stack
| Layer | Technology |
|-------|-----------|
| Framework | Next.js 16 (App Router) |
| Language | TypeScript 5.9 |
| Styling | Tailwind CSS 4 + shadcn/ui |
| Backend | Supabase (Postgres, Auth, Realtime, Storage) |
| AI | OpenAI (GPT-4o-mini for profile generation) |
| Forms | React Hook Form + Zod validation |
| Deployment | Vercel (syd1 region) |
| Node | v22.22.0 |
| React | 19.2.3 |

### Directory Layout

```
/home/ccuser/rateright-v2/
├── .env.local              # Environment variables (Supabase keys, ABR GUID)
├── .env.example            # Template for env vars
├── CLAUDE.md               # Build instructions for Claude Code
├── PRODUCT-SPEC.md         # Full product specification
├── AI-PROFILE-BUILDER.md   # AI profile feature docs
├── UX-IMPLEMENTATION-GUIDE.md  # UX research & implementation
├── VERCEL-DEPLOYMENT.md    # Deployment guide
├── next.config.ts          # Next.js config (security headers, PWA)
├── vercel.json             # Vercel config (syd1 region, headers)
├── package.json            # Dependencies
├── tsconfig.json           # TypeScript config
├── middleware.ts           # Auth middleware
├── docs/
│   └── ABR-INTEGRATION.md  # ABN lookup API docs
├── supabase/
│   └── schema.sql          # Full database schema with RLS policies
├── public/                 # Static assets (PWA manifest, service worker)
└── src/
    ├── app/
    │   ├── layout.tsx              # Root layout
    │   ├── page.tsx                # Landing page
    │   ├── globals.css             # Global styles
    │   ├── api/
    │   │   ├── abn-lookup/route.ts       # ABN verification API
    │   │   ├── ai/generate-profile/route.ts  # AI profile generation
    │   │   ├── auth/verify-email/route.ts    # Email verification
    │   │   └── company-logo/route.ts         # Company logo fetcher
    │   ├── auth/
    │   │   ├── callback/route.ts   # OAuth callback
    │   │   ├── login/page.tsx      # Login page
    │   │   ├── signup/page.tsx     # Signup page
    │   │   └── verify-email/page.tsx
    │   ├── dashboard/page.tsx      # Main dashboard
    │   ├── contractor/
    │   │   ├── signup/page.tsx     # Contractor onboarding (ABN lookup)
    │   │   ├── post-job/page.tsx   # 3-step job posting
    │   │   └── matches/page.tsx    # Worker matches (swipe-to-hire)
    │   ├── worker/
    │   │   ├── signup/page.tsx     # Worker onboarding
    │   │   ├── jobs/page.tsx       # Job listings (swipe-to-apply)
    │   │   └── profile/build/page.tsx  # AI profile builder
    │   └── messages/
    │       ├── page.tsx            # Conversations list
    │       └── [conversationId]/page.tsx  # Chat view
    ├── components/
    │   ├── bottom-nav.tsx          # App bottom navigation
    │   ├── bottom-nav-wrapper.tsx  # Nav wrapper
    │   ├── sign-out-button.tsx     # Sign out component
    │   ├── ConversationPreview.tsx # Message preview card
    │   ├── MessageBubble.tsx       # Chat bubble component
    │   └── ui/                     # shadcn/ui components
    │       ├── avatar.tsx
    │       ├── badge.tsx
    │       ├── button.tsx
    │       ├── card.tsx
    │       ├── dialog.tsx
    │       ├── form.tsx
    │       ├── input.tsx
    │       ├── label.tsx
    │       ├── separator.tsx
    │       ├── sheet.tsx
    │       └── tabs.tsx
    └── lib/
        ├── utils.ts                # Utility functions (cn helper)
        ├── types.ts                # TypeScript types
        ├── abn-utils.ts            # ABN validation (modulus-89)
        ├── company-utils.ts        # Company enrichment utilities
        ├── rate-limit.ts           # API rate limiting
        └── supabase/
            ├── client.ts           # Browser Supabase client
            ├── server.ts           # Server Supabase client
            └── middleware.ts       # Supabase auth middleware
```

### Database Schema (Supabase)
- **URL:** `https://memscjotxrzqnhrvnnkc.supabase.co`
- **Tables:** profiles, companies, worker_profiles, jobs, matches, ratings, payments, notifications
- **RLS:** Enabled on all tables with appropriate policies
- **Auto-trigger:** New auth user → auto-creates profile row
- **Full schema:** `/home/ccuser/rateright-v2/supabase/schema.sql`

### Environment Variables Required
```
NEXT_PUBLIC_SUPABASE_URL=https://memscjotxrzqnhrvnnkc.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=<anon key>
SUPABASE_SERVICE_KEY=<service role key>
ABR_GUID=<ABR web services GUID>
OPENAI_API_KEY=<for AI profile generation>
```

### Git History (recent)
```
c4678a1 feat: messaging UI scaffold
888c3fd feat: Add PWA support
7289787 Add PWA support - manual implementation
caa1620 Add AI Profile Builder documentation
b919a11 Add AI Profile Builder feature
6bad3b9 Add Vercel deployment instructions
75b366c Update UX implementation and authentication pages
033fd7e feat: UX improvements - glove-first design, swipe-to-apply
1bb0e72 feat: RateRight v2 - mobile-first construction hiring platform
```

---

## 4. Deployment

### Primary: Vercel
- **CLI installed:** v50.11.0
- **Config:** `vercel.json` → Next.js framework, `syd1` region, security headers
- **Status:** Ready for deployment but blocked on Vercel auth token
- **Deployment options:**
  1. **GitHub Integration (recommended):** Connect `RateRight-PTY-LTD/the-50-dollar-app` in Vercel dashboard → auto-deploys on push
  2. **CLI:** `vercel deploy --prod --token=$VERCEL_TOKEN`
  3. **Link existing:** `vercel link --token=$VERCEL_TOKEN` then `vercel deploy --prod`
- **Env vars for production:** Set in Vercel dashboard (Project Settings → Environment Variables)

### No Fly.io / Railway / Docker
- No `fly.toml`, `Dockerfile`, or `railway.toml` exists
- No Fly CLI installed
- Railway CLI not installed
- The app is designed for Vercel deployment only

### Development Server
```bash
cd /home/ccuser/rateright-v2
npm run dev     # Next.js dev server (http://localhost:3000)
npm run build   # Production build
npm run start   # Production server
npm run lint    # ESLint
```

---

## 5. Product Context

### What is RateRight?
AI-first construction hiring marketplace for Australia.
- **Contractors** type company name → AI builds profile + writes job posts
- **Workers** answer 4 questions (or send voice note) → AI builds profile
- **$50 flat fee** per confirmed hire. Workers always free.
- **USP:** Every competitor has forms. We have AI.

### Business Model
- $50 per hire, charged to contractor
- Workers pay $0
- No subscriptions, no percentages
- Revenue = $50 × hires/month

### MVP Status (What's Built)
- ✅ Project scaffolding (Next.js + Supabase + Tailwind + shadcn)
- ✅ Database schema with RLS
- ✅ Auth flow (email/phone signup via Supabase)
- ✅ Contractor signup with AI company research (ABN lookup)
- ✅ Worker signup (5-question form)
- ✅ AI profile builder (GPT-4o-mini)
- ✅ Job posting (3-step flow with AI suggestions)
- ✅ Worker job browsing (swipe-to-apply)
- ✅ Contractor match viewing (swipe-to-hire)
- ✅ Dashboard
- ✅ PWA support (manifest + service worker)
- ✅ Messaging UI scaffold
- ✅ UX Phase 1 (64px touch targets, bottom CTAs, swipe gestures)

### MVP Remaining
- ❌ Smart matching algorithm (backend)
- ❌ One-tap hire flow (backend logic)
- ❌ Stripe payment ($50)
- ❌ Push notifications
- ❌ Ratings system (backend)
- ❌ Email notifications
- ❌ Admin dashboard
- ❌ Vercel production deployment

### Phase 2 (Post-MVP)
- Voice profile builder (Whisper)
- React Native mobile apps
- White Card photo verification (Gemini OCR)
- In-app real-time messaging
- Repeat hire suggestions
- Worker availability calendar
- Location-based notifications

### Design Principles
1. **Mobile-first** — phone on construction site
2. **One-tap everything** — minimize friction
3. **AI does the work** — pre-fill, suggest, auto-complete
4. **Ultra simple** — max 3 actions per screen
5. **Fast** — <1s page loads
6. **Australian** — AUD, Aussie English, local references
7. **Glove-friendly** — 64px touch targets minimum
8. **Thumb zone** — primary CTAs in bottom 25% of screen

---

## 6. Key Files to Read Before Coding

| File | Purpose |
|------|---------|
| `CLAUDE.md` | Build instructions, priorities, code style |
| `PRODUCT-SPEC.md` | Full product spec with user flows, DB schema, timeline |
| `UX-IMPLEMENTATION-GUIDE.md` | UX decisions, touch targets, design system |
| `AI-PROFILE-BUILDER.md` | AI profile feature technical docs |
| `docs/ABR-INTEGRATION.md` | ABN lookup API integration docs |
| `VERCEL-DEPLOYMENT.md` | Deployment guide |
| `supabase/schema.sql` | Complete database schema with RLS |

---

## 7. Common Operations

### Build & Test
```bash
cd /home/ccuser/rateright-v2
npm run build              # Check TypeScript compilation + build
npm run dev                # Start dev server on :3000
npm run lint               # Run ESLint
```

### Git Workflow
```bash
cd /home/ccuser/rateright-v2
git status
git add .
git commit -m "feat: description"
git push origin main
```

### Add a shadcn/ui Component
```bash
npx shadcn@latest add <component-name>
# e.g. npx shadcn@latest add toast
```

### Create a New Page
```
src/app/<route>/page.tsx           # Page component
src/app/api/<route>/route.ts       # API route
```

### Supabase Client Usage
```typescript
// Client-side (browser)
import { createClient } from '@/lib/supabase/client'
const supabase = createClient()

// Server-side (API routes, Server Components)
import { createClient } from '@/lib/supabase/server'
const supabase = await createClient()
```

---

## 8. Team & Roles

- **Michael** — Founder, product direction, sales
- **Rivet (AI)** — COO system, AI integrations, testing, ops, orchestration
- **Markus** — Frontend developer (Next.js, Supabase)
- **Builder Agent** — Autonomous coding agent for feature implementation

---

## 9. Infrastructure

- **VPS:** DigitalOcean syd1, 2 vCPU, 8GB RAM (Ubuntu)
- **Supabase:** `memscjotxrzqnhrvnnkc.supabase.co`
- **GitHub Org:** `RateRight-PTY-LTD`
- **Vercel:** Pending production deployment (syd1 region configured)
- **Growth Engine:** `https://rateright-growth-production.up.railway.app` (separate service)

---

## 10. Safety Rules

1. **ALWAYS run Claude Code as `ccuser`, never root**
2. **Never commit secrets** — `.env.local` is gitignored
3. **Never run Claude Code in ~/clawd/** — that's Clawdbot's live instance
4. **Use `trash` over `rm`** for file deletion
5. **git push only to `main`** (single branch workflow currently)
6. **Test builds before pushing** — `npm run build` must pass
7. **Mobile-first** — every change must work on phone screens
8. **Manual fallbacks** — every AI feature needs a non-AI fallback path

---

## 11. Learnings & Gotchas (Updated 2026-02-07)

### What Works Well
1. **Direct fixes beat Claude Code for ≤5 files.** The 3 critical auth fixes (callback, server client, abr_verified) were done manually in ~5 minutes — read file, write fix, build, push. Three CC sessions failed trying to do the same kind of work.
2. **Audit prompts work great.** CC is excellent at reading an entire codebase and writing a thorough analysis. The 48-bug audit was high quality. Use CC for READ tasks, not WRITE tasks when possible.
3. **Always verify before reporting.** Check `git log` and `git status` after CC runs. It often does the work but forgets to commit, or the session dies mid-push.

### What Fails
1. **Mega-prompts with 20+ tasks kill CC sessions.** 3 out of 4 CC sessions died without committing. The prompt was too long, the budget ran out, or it got stuck on one task and burned through tokens.
2. **CC writes report files instead of fixing code.** Even when explicitly told "don't write reports, just fix code," it created 5 markdown report files. Always add: "Do NOT create any .md files. Only modify existing source code."
3. **Two repo copies cause sync issues.** `/home/ccuser/rateright-v2` and `/home/ccuser/the-50-dollar-app` are the same repo but drift apart. Always work from ONE path.

### Patterns to Follow
1. **1-3 tasks per CC session, max.** Break big task lists into atomic CC runs. One commit per session.
2. **Direct fix for small bugs.** If it's ≤5 files and you can see the fix, just do it with read/edit/write tools. Faster, more reliable.
3. **CC for big refactors only.** Use CC when you need to touch 10+ files or do complex multi-step changes.
4. **Always include in CC prompts:**
   - `--dangerously-skip-permissions` (non-interactive)
   - `--max-budget-usd 5.00` (keep sessions small)
   - "Run npm run build, fix errors, git add -A, git commit, git push"
   - "Do NOT create report files. Only modify source code."
   - Wake command at the end
5. **Check CC output within 5 minutes.** If it died, salvage uncommitted changes with `git status` and commit manually.
6. **Sync repos after every push:** `cd /home/ccuser/rateright-v2 && git pull`

### Decision Tree: Direct Fix vs Claude Code
```
Is it ≤5 files and I can see the fix? → Direct fix (read/edit/write)
Is it a refactor touching 10+ files?  → Claude Code (small prompt)
Is it an audit/analysis?              → Claude Code (great at reading)
Is it 6-9 files?                      → Judgment call. Lean toward direct.
```

### Repo Consolidation (TODO)
- Primary path: `/home/ccuser/the-50-dollar-app` (Michael uses this)
- After every push, sync: `cd /home/ccuser/rateright-v2 && git fetch origin && git reset --hard origin/main`
- Long term: delete rateright-v2, symlink if needed

### CC Session Template (copy-paste ready)
```bash
su - ccuser -c 'cd /home/ccuser/the-50-dollar-app && claude --dangerously-skip-permissions -p "TASK: [one clear task]

Do NOT create any markdown or report files. Only modify source code.
After fixing: npm run build (fix any errors), git add -A, git commit -m \"[msg]\", git push origin main.
When finished, run: clawdbot gateway wake --text \"Done: [summary]\" --mode now" --max-budget-usd 5.00 2>&1'
```

---

## TODO.md Task Queue (MANDATORY)

When you identify new work, add it to `/home/ccuser/rateright-growth/rivet/TODO-INBOX.md` with your tag.
- Tag format: `[Builder]`, `[Sales]`, `[Research]`, `[SysOps]`, `[Content]`, `[Product]`, `[SiteOps]`
- Don't wait for permission on obvious tasks.
- Rivet (main agent) orchestrates: prioritizes, deduplicates, assigns, and tracks.
- You generate and execute. Rivet coordinates.