# Crew Listings Feature Specification

**Version:** 1.0  
**Date:** 2026-02-07  
**Author:** Rivet (COO System)  
**Status:** Draft for Review

---

## Executive Summary

Crew Listings enables experienced crew leaders to list their entire team on RateRight, allowing contractors to hire a complete, proven crew for a flat $100 fee. This addresses the real-world need for teams that already work well together on formwork, steelfixing, and concrete pours.

### Key Value Proposition

| Stakeholder | Current Pain | Crew Listings Solution |
|-------------|--------------|------------------------|
| **Contractors** | Hiring 4 individuals = 4×$50 = $200 + coordination hassle | One booking, $100, team that's worked together |
| **Crew Leaders** | No platform recognises their role, lose crew to individual gigs | Formalised leadership, consistent team work |
| **Crew Members** | Scattered work, can't leverage team reputation | Regular work with trusted crew, shared reputation |

---

## Research Findings

### How Construction Crews Work

**Team Structure:**
- **Crew Leader/Foreman:** Manages 3-8 workers on site, single point of contact for contractor
- **Responsibilities:** Planning workloads, delegating tasks, quality control, training new hires
- **Trust:** Crew leaders develop loyal teams over years—workers prefer sticking with good leaders

**Sydney Market Insights:**
- Formwork/steelfixing crews typically 4-6 workers
- Day rate for labourers: $35-55/hour ($280-440/day)
- Labour hire agencies charge $52-150/hour per worker (20-40% margin)
- Crews that work together are 30-50% more efficient than assembled strangers

**Payment Dynamics:**
- Traditional: General contractor → Subcontractor (crew leader) → Individual wages
- Crew leaders often operate as subcontractors (own ABN, invoice for whole team)
- Workers may be employees of crew leader OR independent contractors
- Payment disputes most common with ad-hoc hires, rare with established subcontractor relationships

### Trust & Verification Requirements

**Mandatory for Sydney construction:**
- **White Card:** All workers must hold valid construction induction card
- **Verification:** Employers legally obligated to check via SafeWork NSW Verify.licence portal
- **ABN:** Crew leaders operating as subcontractors need registered ABN

**Platform trust signals:**
- Combined crew experience (years worked together)
- Individual + crew ratings
- Completed job photos
- White Card verification badges

---

## User Stories

### Crew Leader Perspective

**Primary Goal:** Get consistent work for my team without platform eating our margins.

| Story | Priority |
|-------|----------|
| As a crew leader, I want to create a crew profile that showcases my team's skills so contractors see we're proven professionals | P0 |
| As a crew leader, I want to add/remove crew members so my listing stays current | P0 |
| As a crew leader, I want to set our availability and specialisation so we get relevant job offers | P0 |
| As a crew leader, I want to receive $100 directly and distribute to my crew as I see fit | P0 |
| As a crew leader, I want to accept/reject booking requests so I control our schedule | P1 |
| As a crew leader, I want crew-level ratings that reflect our teamwork quality | P1 |

**Persona: "Steve the Steelfixer"**
> *"I've got 4 blokes who've worked with me for 3 years. High-rises, foundations, you name it. Agencies take 30% and I still have to find my own guys. Give me a listing where contractors see we're a package deal—saves everyone time."*

### Contractor Perspective

**Primary Goal:** Get a reliable team on site fast, without interviewing 6 strangers.

| Story | Priority |
|-------|----------|
| As a contractor, I want to search for crews by size, trade, and availability | P0 |
| As a contractor, I want to see crew ratings AND individual member profiles | P0 |
| As a contractor, I want to pay $100 and get the whole team's contact info | P0 |
| As a contractor, I want to know all members have verified White Cards | P0 |
| As a contractor, I want to message crew leader before booking to confirm details | P1 |
| As a contractor, I want to rate the crew after the job | P1 |

**Persona: "Tony the Builder"**
> *"Last week I hired 4 guys off different platforms. 2 showed up late, 1 couldn't read drawings, and they argued about whose job was what. Never again. I'll pay for a crew that knows each other."*

### Crew Member Perspective

**Primary Goal:** Regular work with people I trust, building reputation through team success.

| Story | Priority |
|-------|----------|
| As a crew member, I want to be part of a crew listing without managing it myself | P0 |
| As a crew member, I want my individual skills shown within the crew profile | P1 |
| As a crew member, I want to see upcoming crew bookings | P1 |
| As a crew member, I want the option to leave a crew and work solo | P2 |
| As a crew member, I want my individual rating to benefit from crew performance | P2 |

**Persona: "Marco the Labourer"**
> *"Steve's crew is solid. He finds the work, I show up and do my bit. The crew gets rated well because we work well together. I don't want to manage a profile—just want to be listed with the team."*

---

## Pricing Model Recommendation

### Analysis: $100 Crew Fee vs $50 Per Worker

**Option A: Flat $100 for any crew (3-8 members)**
| Pros | Cons |
|------|------|
| Simple pricing, easy to understand | Less revenue for larger crews |
| Significant value vs individual hires | May attract low-quality "fake crews" |
| Encourages crew formation | 3-person crew pays same as 8-person |

**Option B: Tiered by crew size**
| Crew Size | Fee | Per-Worker Equivalent |
|-----------|-----|----------------------|
| 3-4 workers | $100 | $25-33 |
| 5-6 workers | $125 | $21-25 |
| 7-8 workers | $150 | $19-21 |

**Option C: Per-worker discount ($35 per worker)**
| Crew Size | Total Fee | Savings vs Individual |
|-----------|-----------|----------------------|
| 3 workers | $105 | $45 (30%) |
| 4 workers | $140 | $60 (30%) |
| 6 workers | $210 | $90 (30%) |

### Recommendation: Start with Flat $100

**Rationale:**
1. **Simplicity wins:** "Hire a crew for $100" is memorable and shareable
2. **Low friction:** Contractors don't calculate, just book
3. **Market positioning:** Dramatically undercuts agencies
4. **Test hypothesis:** See if larger crews game the system before complicating pricing
5. **Sydney market reality:** Most crews are 4-5 workers, sweet spot for $100

**Future iteration:** If 7-8 person "crews" become problematic, add tiered pricing in Phase 2.

### Insurance Consideration

**Crew Insurance: $10/week per member (unchanged)**
- Individual crew members can still opt into the $10/week insurance
- Crew leader can encourage or require it
- Claim process unchanged (individual claims their own wages)

---

## Feature Requirements

### MVP (Phase 1)

#### Crew Profile Creation

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| Crew name | Text (50 chars) | Yes | e.g., "Steve's Steelfixers" |
| Primary trade | Select | Yes | Steelfixing, Formwork, Concreting, General Labour, Mixed |
| Crew leader | User ID | Yes | Auto-set to creator |
| Description | Text (500 chars) | No | Sell the crew's strengths |
| Years working together | Number | No | Trust signal |
| Service areas | Multi-select | Yes | Sydney suburbs/regions |
| Crew photo | Image | No | Team shot on site |

#### Member Management

| Feature | Description |
|---------|-------------|
| Add member | Crew leader invites by phone/email, member confirms |
| Remove member | Crew leader can remove, member can leave |
| Member count | Minimum 3, maximum 8 (enforced) |
| White Card verification | Each member must upload for crew to be listed |
| Role assignment | Crew leader assigns trade/role per member |

#### Crew Listing Display

```
┌─────────────────────────────────────────────┐
│ 🔨 Steve's Steelfixers                 ⭐ 4.8│
│ Steelfixing · 4 workers · 3 years together  │
├─────────────────────────────────────────────┤
│ ✓ All White Cards verified                  │
│ 📍 Parramatta, Liverpool, Penrith          │
│                                             │
│ Specialising in high-rise steelfixing and   │
│ foundation work. Our crew has completed     │
│ 50+ commercial projects together.           │
├─────────────────────────────────────────────┤
│ CREW MEMBERS                                │
│ • Steve (Leader) - Steelfixer ⭐ 4.9        │
│ • Marco - Labourer ⭐ 4.7                   │
│ • Danny - Steelfixer ⭐ 4.8                 │
│ • Tom - Labourer ⭐ 4.6                     │
├─────────────────────────────────────────────┤
│ [HIRE CREW - $100]        [MESSAGE LEADER]  │
└─────────────────────────────────────────────┘
```

#### Booking Flow

```
Contractor                      RateRight                    Crew Leader
    │                              │                              │
    ├── Browse crews ──────────────►│                              │
    │                              │                              │
    ├── Select dates, send request─►│                              │
    │                              ├── Notification ──────────────►│
    │                              │                              │
    │                              │◄── Accept (2hr timeout) ──────┤
    │                              │                              │
    │◄── Pay $100 prompt ──────────┤                              │
    │                              │                              │
    ├── Payment complete ──────────►│                              │
    │                              ├── Release contact info ──────►│
    │                              │◄─────────────────────────────┤
    │◄── Crew leader contact ──────┤                              │
    │                              │                              │
    ├── Job happens (off-platform) ────────────────────────────────┤
    │                              │                              │
    │◄── Rate crew prompt ─────────┤                              │
    ├── Submit rating ─────────────►│◄── Rate contractor ─────────┤
    │                              │                              │
```

#### Search & Discovery

| Filter | Options |
|--------|---------|
| Trade | Steelfixing, Formwork, Concreting, General Labour, Mixed |
| Crew size | 3-4, 5-6, 7-8 |
| Available dates | Date picker |
| Service area | Sydney suburbs/regions |
| Minimum rating | 4.0+, 4.5+, Any |
| Sort by | Rating, Availability, Newest |

### Phase 2 Enhancements

- Availability calendar (crew leader manages)
- Equipment listings ("we bring scaffolding")
- Past job photos/portfolio
- Favourite crews
- Repeat booking discounts
- Dynamic pricing by crew size

### Phase 3 Scale

- Crew formation suggestions (AI matches individuals into crews)
- Insurance bundle discounts
- Multi-day project bookings
- Verified contractor deposits for new crews

---

## Database Schema Additions

### New Tables

```sql
-- Crews table
CREATE TABLE crews (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  name VARCHAR(100) NOT NULL,
  leader_id UUID NOT NULL REFERENCES users(id),
  primary_trade VARCHAR(50) NOT NULL,
  description TEXT,
  years_together INTEGER DEFAULT 0,
  service_areas TEXT[] NOT NULL,
  photo_url VARCHAR(500),
  rating_avg DECIMAL(3,2) DEFAULT 0.00,
  rating_count INTEGER DEFAULT 0,
  total_hires INTEGER DEFAULT 0,
  status VARCHAR(20) DEFAULT 'draft', -- draft, active, suspended, archived
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Crew members junction table
CREATE TABLE crew_members (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  crew_id UUID NOT NULL REFERENCES crews(id) ON DELETE CASCADE,
  user_id UUID NOT NULL REFERENCES users(id),
  role VARCHAR(50) NOT NULL, -- Steelfixer, Labourer, Formworker, etc.
  is_leader BOOLEAN DEFAULT FALSE,
  white_card_verified BOOLEAN DEFAULT FALSE,
  white_card_number VARCHAR(50),
  joined_at TIMESTAMPTZ DEFAULT NOW(),
  left_at TIMESTAMPTZ, -- NULL if active
  UNIQUE(crew_id, user_id)
);

-- Crew bookings
CREATE TABLE crew_bookings (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  crew_id UUID NOT NULL REFERENCES crews(id),
  contractor_id UUID NOT NULL REFERENCES users(id),
  job_date DATE NOT NULL,
  job_duration_days INTEGER DEFAULT 1,
  job_description TEXT,
  job_location VARCHAR(200),
  fee_amount DECIMAL(10,2) DEFAULT 100.00,
  platform_fee DECIMAL(10,2) DEFAULT 20.00, -- 20% to RateRight
  status VARCHAR(20) DEFAULT 'pending', 
    -- pending, accepted, rejected, expired, paid, completed, cancelled
  requested_at TIMESTAMPTZ DEFAULT NOW(),
  accepted_at TIMESTAMPTZ,
  paid_at TIMESTAMPTZ,
  completed_at TIMESTAMPTZ,
  expires_at TIMESTAMPTZ, -- 2 hours after request
  contractor_rating INTEGER CHECK (contractor_rating >= 1 AND contractor_rating <= 5),
  contractor_review TEXT,
  crew_rating INTEGER CHECK (crew_rating >= 1 AND crew_rating <= 5),
  crew_review TEXT
);

-- Crew availability (optional, Phase 2)
CREATE TABLE crew_availability (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  crew_id UUID NOT NULL REFERENCES crews(id) ON DELETE CASCADE,
  date DATE NOT NULL,
  is_available BOOLEAN DEFAULT TRUE,
  notes VARCHAR(200),
  UNIQUE(crew_id, date)
);
```

### Indexes

```sql
CREATE INDEX idx_crews_status ON crews(status);
CREATE INDEX idx_crews_primary_trade ON crews(primary_trade);
CREATE INDEX idx_crews_leader ON crews(leader_id);
CREATE INDEX idx_crew_members_crew ON crew_members(crew_id);
CREATE INDEX idx_crew_members_user ON crew_members(user_id);
CREATE INDEX idx_crew_bookings_crew ON crew_bookings(crew_id);
CREATE INDEX idx_crew_bookings_contractor ON crew_bookings(contractor_id);
CREATE INDEX idx_crew_bookings_status ON crew_bookings(status);
CREATE INDEX idx_crew_bookings_date ON crew_bookings(job_date);
```

### User Table Additions

```sql
-- Add to existing users table
ALTER TABLE users ADD COLUMN IF NOT EXISTS is_crew_leader BOOLEAN DEFAULT FALSE;
ALTER TABLE users ADD COLUMN IF NOT EXISTS crew_id UUID REFERENCES crews(id);
```

---

## UI Flows

### Flow 1: Crew Leader Creates Crew

```
┌────────────────────────┐
│   CREATE YOUR CREW     │
│                        │
│  Crew Name             │
│  ┌──────────────────┐  │
│  │ Steve's Steelfixers│ │
│  └──────────────────┘  │
│                        │
│  Primary Trade         │
│  ┌──────────────────┐  │
│  │ Steelfixing    ▼ │  │
│  └──────────────────┘  │
│                        │
│  Service Areas         │
│  ☑ Parramatta          │
│  ☑ Liverpool           │
│  ☐ Penrith             │
│  ☐ Blacktown           │
│                        │
│  ┌──────────────────┐  │
│  │    NEXT →        │  │
│  └──────────────────┘  │
└────────────────────────┘
         │
         ▼
┌────────────────────────┐
│   ADD CREW MEMBERS     │
│                        │
│  Invite by phone:      │
│  ┌──────────────────┐  │
│  │ 0412 345 678     │  │
│  └──────────────────┘  │
│  ┌──────────────────┐  │
│  │   + ADD MEMBER   │  │
│  └──────────────────┘  │
│                        │
│  Pending Invites (2)   │
│  ├─ Marco (Labourer)   │
│  └─ Danny (Steelfixer) │
│                        │
│  Confirmed (1)         │
│  ├─ Tom ✓ White Card   │
│                        │
│  Min 3 members to list │
│                        │
│  ┌──────────────────┐  │
│  │  PUBLISH CREW    │  │
│  └──────────────────┘  │
└────────────────────────┘
```

### Flow 2: Contractor Books Crew

```
┌────────────────────────┐
│   STEVE'S STEELFIXERS  │
│   ⭐ 4.8 · 4 workers   │
├────────────────────────┤
│                        │
│  Select Date:          │
│  ┌──────────────────┐  │
│  │ Mon 10 Feb 2026  │  │
│  └──────────────────┘  │
│                        │
│  Job Location:         │
│  ┌──────────────────┐  │
│  │ 123 Building St  │  │
│  └──────────────────┘  │
│                        │
│  Job Details:          │
│  ┌──────────────────┐  │
│  │ Foundation pour  │  │
│  │ Level 2 slab     │  │
│  └──────────────────┘  │
│                        │
│  ┌──────────────────┐  │
│  │  REQUEST CREW    │  │
│  │      $100        │  │
│  └──────────────────┘  │
└────────────────────────┘
         │
         ▼
┌────────────────────────┐
│   REQUEST SENT ✓       │
│                        │
│  Waiting for Steve to  │
│  accept your request.  │
│                        │
│  ⏱ Expires in 1:58:32  │
│                        │
│  We'll notify you when │
│  they respond.         │
│                        │
└────────────────────────┘
```

---

## Edge Cases & Mitigations

### Edge Case 1: Crew Member No-Show

**Scenario:** Contractor books 4-person crew, only 3 show up.

**Mitigation:**
- No automatic refund (contractor deals with crew leader directly)
- Contractor can reflect in review
- Repeated issues → crew suspension
- Future: Partial refund mechanism based on % attendance

### Edge Case 2: Crew Leader Leaves Platform

**Scenario:** Crew leader deletes account or goes inactive.

**Mitigation:**
- Crew is archived, not deleted
- Members notified and can form new crew
- Highest-rated member offered leadership
- Pending bookings refunded

### Edge Case 3: Fake Crews

**Scenario:** Individual creates "crew" with fake members to get $100 fee.

**Mitigation:**
- Each member must confirm via their own account
- White Card verification required per member
- Minimum 3 verified members to publish
- Review patterns flagged by system

### Edge Case 4: Member Disputes Payment Split

**Scenario:** Crew member claims leader didn't pay them.

**Mitigation:**
- RateRight pays crew leader only
- Internal payment is between leader and members
- Terms make this explicit
- Optional: Future integration with direct member payments

### Edge Case 5: Overlapping Bookings

**Scenario:** Crew accepts two jobs for same date.

**Mitigation:**
- Crew leader must manage availability
- System shows warning if booking same date
- Phase 2: Automated availability calendar
- Double-booking = automatic 1-star rating penalty

### Edge Case 6: Mixed Crew Ratings

**Scenario:** Crew has 4.9 leader but 3.5 member.

**Display:**
- Show crew average prominently
- Show individual ratings on member hover/tap
- Weight leader rating slightly higher (they manage quality)

---

## Implementation Phases

### Phase 1: MVP (4-6 weeks)

**Week 1-2: Backend**
- [ ] Create database schema
- [ ] Crew CRUD API endpoints
- [ ] Member invitation system
- [ ] White Card verification flow (manual for MVP)

**Week 3-4: Frontend**
- [ ] Crew creation wizard
- [ ] Member management screens
- [ ] Crew listing cards
- [ ] Search/filter interface

**Week 5-6: Booking & Payments**
- [ ] Booking request flow
- [ ] $100 payment via Stripe
- [ ] Accept/reject notifications
- [ ] Basic rating system

**Go-Live Checklist:**
- [ ] 5 test crews onboarded
- [ ] Stripe crew booking product created
- [ ] Email templates for booking notifications
- [ ] Mobile responsive (glove-friendly)

### Phase 2: Enhancement (4 weeks)

- [ ] Availability calendar
- [ ] Equipment listings
- [ ] Job photos/portfolio
- [ ] Favourite crews
- [ ] Push notifications
- [ ] Crew leader dashboard (earnings, upcoming jobs)

### Phase 3: Scale (Ongoing)

- [ ] Tiered pricing (if needed)
- [ ] Multi-day bookings
- [ ] Verified contractor deposits
- [ ] AI crew formation suggestions
- [ ] Insurance bundle deals
- [ ] Crew certifications (safety, trade-specific)

---

## Success Metrics

### Business Metrics (Phase 1)

| Metric | Target (Month 1) | Target (Month 3) |
|--------|------------------|------------------|
| Crews created | 10 | 50 |
| Crew bookings | 5 | 30 |
| Booking conversion rate | 15% | 25% |
| Revenue from crews | $500 | $3,000 |
| Repeat bookings | - | 40% |

### Quality Metrics

| Metric | Target |
|--------|--------|
| Average crew rating | 4.5+ |
| Booking acceptance rate | 80%+ |
| No-show rate | <5% |
| Contractor satisfaction | 4.5+ stars |
| Support tickets per booking | <0.1 |

### Growth Indicators

| Signal | Meaning |
|--------|---------|
| Individuals forming crews | Product-market fit |
| Contractors requesting crews | Demand validation |
| Word-of-mouth referrals | Trust established |
| Repeat contractor bookings | Value delivered |

---

## Open Questions for Review

1. **Payment to whom?** Crew leader only (simpler) or option for direct member payments (complex but fairer)?

2. **Minimum crew size?** 3 members (proposed) or 4 to ensure real teams?

3. **Tiered pricing trigger:** At what point do we add tiered pricing if needed?

4. **Insurance requirement:** Should crew listings require all members to have $10/week insurance?

5. **Contractor deposit:** For first-time contractors booking crews, require $100 deposit to prevent no-shows?

---

## Appendix: Competitive Landscape

| Platform | Crew Feature | Pricing |
|----------|--------------|---------|
| Gumtree | No | Free |
| Seek | No | Per-ad |
| Hipages | No | Per-lead |
| Airtasker | No | 15-20% |
| Labour hire agencies | Yes (their crews) | 20-40% markup |
| **RateRight** | **Yes (worker-owned crews)** | **$100 flat** |

**Unique Position:** Only platform where workers own and control their crew listings, keeping 100% of their rate while contractors get proven teams at a fraction of agency costs.

---

*Spec created by Rivet for RateRight crew listings feature. Ready for Michael's review and prioritisation.*