oneie
Version:
Build apps, websites, and AI agents in English. Zero-interaction setup for AI agents (Claude Code, Cursor, Windsurf). Download to your computer, run in the cloud, deploy to the edge. Open source and free forever.
1,687 lines (1,238 loc) • 42.6 kB
Markdown
---
title: Wave1 Onboarding 100 Cycles
dimension: things
category: plans
tags: agent, ai, backend, claude, frontend, cycle, ontology, testing
related_dimensions: connections, events, groups, knowledge, people
scope: global
created: 2025-11-03
updated: 2025-11-03
version: 1.0.0
ai_context: |
This document is part of the things dimension in the plans category.
Location: one/things/plans/wave1-onboarding-100-cycles.md
Purpose: Documents wave 1: creator onboarding - 100-cycle execution plan
Related dimensions: connections, events, groups, knowledge, people
For AI agents: Read this to understand wave1 onboarding 100 cycles.
---
# Wave 1: Creator Onboarding - 100-Cycle Execution Plan
**Version:** 1.0.0
**Total Cycles:** 100 (Cycle 1-100)
**Estimated Duration:** 10-12 days (8-10 cycles per specialist per day)
**Team:** 4 specialists + 1 orchestrator (director)
---
## Overview: The 100-Cycle Breakdown
```
Cycle 1-10: FOUNDATION & ONTOLOGY VALIDATION
Cycle 11-20: BACKEND SCHEMA & SERVICES
Cycle 21-30: BACKEND MUTATIONS & QUERIES
Cycle 31-40: FRONTEND PAGES & COMPONENTS (Part 1)
Cycle 41-50: FRONTEND PAGES & COMPONENTS (Part 2)
Cycle 51-60: API ROUTES & INTEGRATIONS
Cycle 61-70: EMAIL & VERIFICATION SYSTEM
Cycle 71-80: TEAM MANAGEMENT & WORKSPACE
Cycle 81-90: TESTING & QUALITY ASSURANCE
Cycle 91-100: DEPLOYMENT & DOCUMENTATION
```
Each phase has dependencies clearly marked. **Bold dependencies** block downstream work.
---
## PHASE 1: FOUNDATION & VALIDATION (Cycle 1-10)
**Specialist:** Agent-Director (Orchestration)
**Duration:** 1-2 days
**Output:** Approved vision, ontology mapping, task lists
### Cycle 1: Confirm 6-Dimension Ontology Alignment
**Task:** Validate onboarding maps to ALL 6 dimensions
**Checklist:**
- [ ] Groups dimension: Workspace group creation ✓
- [ ] People dimension: Creator person + team roles ✓
- [ ] Things dimension: Creator, workspace, tokens, preferences ✓
- [ ] Connections dimension: member_of, owns, transacted ✓
- [ ] Events dimension: user_registered, email_verified, profile_updated, etc ✓
- [ ] Knowledge dimension: Skill labels, interest labels, taxonomy ✓
**Deliverable:** `/wave1-onboarding-vision.md` (completed)
**Status:** ✅ COMPLETE
**Decision Gate:**
- If ANY dimension missing → Rethink feature
- If all aligned → Proceed to Cycle 2
---
### Cycle 2: Define Complete Entity Types
**Task:** Specify exact properties for creator, workspace, invitation tokens
**Creator Properties:**
```typescript
{
type: 'creator',
name: string,
properties: {
email: string,
username: string,
displayName: string,
bio: string,
avatar: string,
// Profile
niche: string[], // [fitness, education, business]
expertise: string[], // Skills
interests: string[], // Topics
// Workspace
workspaceId: Id<'groups'>,
workspaces: Id<'groups'>[],
role: 'owner' | 'admin' | 'editor',
// Wallet
walletAddress: string,
walletVerified: boolean,
walletConnectedAt: number,
// Onboarding
onboardingStep: 'signup' | 'verify' | 'profile' | 'workspace' | 'team' | 'wallet' | 'skills' | 'complete',
onboardingCompleted: boolean,
onboardingCompletedAt: number,
onboardingTourStarted: boolean,
onboardingTourCompleted: boolean,
// Settings
emailVerified: boolean,
emailVerifiedAt: number,
twoFactorEnabled: boolean,
preferredLanguage: string,
timezone: string,
// Stats
totalTeamMembers: number,
totalContentCreated: number,
totalEarnings: number,
// Terms
agreeToTerms: boolean,
agreeToPrivacy: boolean,
marketingEmails: boolean,
}
}
```
**Organization (Workspace) Properties:**
```typescript
{
type: 'organization',
name: string,
properties: {
slug: string,
description: string,
logo: string,
visibility: 'private' | 'public',
joinPolicy: 'invite_only' | 'open',
memberCount: number,
maxMembers: number,
plan: 'free' | 'pro' | 'enterprise',
planUpgradedAt: number,
stripeCustomerId: string,
billingEmail: string,
defaultLanguage: string,
defaultTimezone: string,
}
}
```
**Invitation Token Properties:**
```typescript
{
type: 'invitation_token',
name: string,
properties: {
token: string,
invitedBy: Id<'things'>,
invitedEmail: string,
workspaceId: Id<'groups'>,
role: 'editor' | 'viewer',
status: 'pending' | 'accepted' | 'expired',
expiresAt: number,
acceptedAt: number,
acceptedBy: Id<'things'>,
}
}
```
**Deliverable:** Type specification document
**Status:** ✅ COMPLETE (from vision doc)
---
### Cycle 3: Define Event Types to Log
**Task:** List all events that need logging during onboarding
**Event Types to Create:**
1. `user_registered` - Signup form submitted
2. `email_verification_sent` - Code sent to email
3. `email_verified` - Email confirmed
4. `profile_updated` - Profile form submitted
5. `thing_created` (thingType: organization) - Workspace created
6. `user_invited_to_group` - Team member invited
7. `user_joined_group` - Team member accepted invitation
8. `wallet_connected` - Crypto wallet linked
9. `thing_updated` (thingType: creator) - Skills added
10. `onboarding_completed` - Full journey done
**Event Logging Strategy:**
- Every state transition → event logged
- Metadata captures context (source, device, values changed)
- Timestamp precise (milliseconds)
- Actor ID always logged (who did this)
**Deliverable:** Event specification
**Status:** ✅ COMPLETE
---
### Cycle 4: Define Connection Types
**Task:** Specify relationships that onboarding creates
**Connections to Create:**
1. **Creator → Workspace Group (member_of)**
```
{
fromThingId: creatorId,
toThingId: workspaceGroupId,
relationshipType: 'member_of',
metadata: {
role: 'group_owner',
permissions: ['*'],
joinedAt: Date.now(),
}
}
```
2. **Team Member → Workspace Group (member_of)**
```
{
fromThingId: teamMemberId,
toThingId: workspaceGroupId,
relationshipType: 'member_of',
metadata: {
role: 'group_user',
permissions: ['read', 'write'],
invitedBy: creatorId,
invitedAt: Date.now(),
status: 'pending' | 'active',
}
}
```
**Deliverable:** Connection specification
**Status:** ✅ COMPLETE
---
### Cycle 5: Define Knowledge Labels
**Task:** Specify skill + interest taxonomy for tagging
**Skill Label Categories:**
```
Prefix: skill:*
skill:video-editing
skill:copywriting
skill:social-media
skill:graphic-design
skill:course-creation
skill:podcast-production
skill:community-management
skill:sales-funnel
skill:email-marketing
skill:seo
... (100+ predefined skills)
Prefix: industry:*
industry:fitness
industry:education
industry:finance
industry:entertainment
industry:ecommerce
industry:marketing
industry:technology
industry:wellness
... (50+ predefined industries)
Prefix: goal:*
goal:income
goal:audience
goal:collaboration
goal:learning
goal:brand-building
goal:automation
Prefix: interest:*
interest:personal-branding
interest:monetization
interest:ai-automation
interest:team-management
interest:content-distribution
... (free-form, user-created)
```
**Knowledge Pattern:**
```typescript
// Create knowledge item for each skill
{
knowledgeType: 'label',
text: 'Video Editing',
labels: ['skill:video-editing', 'category:technical'],
metadata: { category: 'skill', searchable: true }
}
// Link creator to knowledge
{
thingId: creatorId,
knowledgeId: skillLabelId,
role: 'label',
metadata: { proficiency: 'intermediate' }
}
```
**Deliverable:** Taxonomy specification
**Status:** ✅ COMPLETE
---
### Cycle 6: Create Implementation Checklist
**Task:** Break down into manageable tasks for specialists
**Backend Tasks (Cycle 11-30):**
- [ ] Extend creator entity type
- [ ] Extend organization entity type
- [ ] Create invitation_token entity type
- [ ] Create onboarding service (Effect.ts)
- [ ] Create signup mutation
- [ ] Create email verification mutation
- [ ] Create profile update mutation
- [ ] Create workspace creation mutation
- [ ] Create team invitation mutation
- [ ] Create invitation acceptance mutation
- [ ] Create wallet connection mutation
- [ ] Create skill tagging mutation
- [ ] Create all queries (status, users, workspaces, members)
- [ ] Set up email templates (Resend)
- [ ] Create verification system (codes, tokens, expiry)
- [ ] Create rate limiting rules
**Frontend Tasks (Cycle 31-50):**
- [ ] Create SignupForm component
- [ ] Create EmailVerification component
- [ ] Create ProfileForm component
- [ ] Create WorkspaceSetup component
- [ ] Create WalletConnection component
- [ ] Create SkillSelection component
- [ ] Create OnboardingTour component
- [ ] Create OnboardingChecklist component
- [ ] Create onboarding pages (8 Astro pages)
- [ ] Create team management page
- [ ] Create API routes (signup, verify, profile, workspace, team)
- [ ] Create auth middleware
- [ ] Create redirect logic
**Quality Tasks (Cycle 81-90):**
- [ ] Write unit tests (mutations, services)
- [ ] Write integration tests (full flows)
- [ ] Write E2E tests (signup to dashboard)
- [ ] Create test accounts + fixtures
- [ ] Run accessibility audit
- [ ] Run performance audit
- [ ] Run security audit
**Designer Tasks (Cycle 41-60 parallel):**
- [ ] Create wireframes for 8 stages
- [ ] Design component specs
- [ ] Create accessibility guide
- [ ] Design mobile layouts
**Documentation Tasks (Cycle 91-100):**
- [ ] User guide
- [ ] API documentation
- [ ] Developer setup guide
- [ ] Deployment checklist
**Deliverable:** Complete task breakdown
**Status:** ✅ COMPLETE
---
### Cycle 7-10: Reserve for Blockers/Contingency
**Task:** Leave buffer for unexpected issues
**Possible issues:**
- Better Auth integration complexity
- Rate limiting complexity
- Email delivery problems
- Database index optimization
- Security review findings
- Performance optimization
- Mobile responsiveness issues
**Reserve:** 4 cycles (4 days of buffer)
---
## PHASE 2: BACKEND SCHEMA & SERVICES (Cycle 11-30)
**Specialist:** Agent-Backend
**Duration:** 3-4 days (20 cycles)
**Dependency:** ✅ Phase 1 complete
**Blocks:** Phase 3 (can't build frontend without backend mutations)
### Cycle 11-12: Extend Creator Entity Type
**Task:** Update `schema.ts` to include all creator properties
**Files to modify:**
- `/backend/convex/schema.ts` - Add creator properties to entities table
**Deliverable:** Updated schema with creator type
**Output file:** `/backend/convex/schema.ts`
**Status:** Ready for implementation
### Cycle 13-14: Extend Organization Entity Type
**Task:** Add organization properties (workspace)
**Files to modify:**
- `/backend/convex/schema.ts` - Add organization properties
**Deliverable:** Updated schema with organization type
**Status:** Ready for implementation
### Cycle 15-16: Create Invitation Token Type
**Task:** Add invitation_token entity type
**Files to modify:**
- `/backend/convex/schema.ts` - Add invitation_token type
**Deliverable:** Updated schema with invitation_token type
**Status:** Ready for implementation
### Cycle 17: Create Onboarding Service (Effect.ts)
**Task:** Build pure business logic service
**File to create:** `/backend/convex/services/onboarding.ts`
**Methods:**
```typescript
export interface OnboardingService {
registerUser(email: string, password: string): Effect<CreatorEntity>;
sendVerificationEmail(userId: Id<"things">, email: string): Effect<void>;
verifyEmail(
userId: Id<"things">,
code: string,
): Effect<{ verified: boolean }>;
updateProfile(userId: Id<"things">, data: ProfileData): Effect<CreatorEntity>;
createWorkspace(
userId: Id<"things">,
name: string,
): Effect<OrganizationEntity>;
inviteTeamMember(
userId: Id<"things">,
workspaceId: Id<"groups">,
email: string,
role: string,
): Effect<void>;
acceptInvitation(token: string): Effect<{ joined: boolean }>;
connectWallet(
userId: Id<"things">,
address: string,
): Effect<{ verified: boolean }>;
addSkills(userId: Id<"things">, skills: string[]): Effect<CreatorEntity>;
completeOnboarding(userId: Id<"things">): Effect<{ completed: boolean }>;
}
```
**Deliverable:** Onboarding service with all business logic
**Status:** Ready for implementation
### Cycle 18: Create Signup Mutation
**Task:** Implement `signUp` mutation (call Better Auth + Convex)
**File to create:** `/backend/convex/mutations/auth.ts`
```typescript
export const signUp = mutation({
args: {
email: v.string(),
password: v.string(),
agreeToTerms: v.boolean(),
agreeToPrivacy: v.boolean(),
},
handler: async (ctx, args) => {
// 1. Validate email doesn't exist
// 2. Hash password
// 3. Create user in Better Auth
// 4. Create creator entity
// 5. Log user_registered event
// 6. Return user + session
},
});
```
**Deliverable:** Working signup mutation
**Status:** Ready for implementation
### Cycle 19: Create Email Verification Mutation
**Task:** Implement `verifyEmail` mutation
**File to update:** `/backend/convex/mutations/auth.ts`
```typescript
export const verifyEmail = mutation({
args: {
code: v.string(),
},
handler: async (ctx, args) => {
// 1. Validate code format + expiry
// 2. Find matching verification token
// 3. Mark creator as emailVerified
// 4. Log email_verified event
// 5. Return success
},
});
```
**Deliverable:** Email verification mutation
**Status:** Ready for implementation
### Cycle 20: Create Profile Update Mutation
**Task:** Implement `updateProfile` mutation
**File to update:** `/backend/convex/mutations/auth.ts`
```typescript
export const updateProfile = mutation({
args: {
displayName: v.string(),
username: v.string(),
bio: v.string(),
niche: v.array(v.string()),
avatar: v.optional(v.string()),
},
handler: async (ctx, args) => {
// 1. Validate username is unique
// 2. Upload avatar if provided
// 3. Update creator properties
// 4. Log profile_updated event
// 5. Return updated creator
},
});
```
**Deliverable:** Profile update mutation
**Status:** Ready for implementation
### Cycle 21: Create Workspace Creation Mutation
**Task:** Implement `createWorkspace` mutation
**File to create:** `/backend/convex/mutations/workspace.ts`
```typescript
export const createWorkspace = mutation({
args: {
name: v.string(),
slug: v.string(),
visibility: v.union(v.literal("private"), v.literal("public")),
},
handler: async (ctx, args) => {
// 1. Validate slug is unique
// 2. Create group entity
// 3. Create member_of connection (creator → workspace)
// 4. Update creator.workspaceId
// 5. Log thing_created event
// 6. Return workspace
},
});
```
**Deliverable:** Workspace creation mutation
**Status:** Ready for implementation
### Cycle 22: Create Team Invitation Mutation
**Task:** Implement `inviteTeamMember` mutation
**File to update:** `/backend/convex/mutations/workspace.ts`
```typescript
export const inviteTeamMember = mutation({
args: {
workspaceId: v.id("groups"),
email: v.string(),
role: v.union(v.literal("editor"), v.literal("viewer")),
},
handler: async (ctx, args) => {
// 1. Validate workspace exists + user is owner
// 2. Generate invitation token
// 3. Create invitation_token entity
// 4. Send invitation email
// 5. Log user_invited_to_group event
// 6. Return invitation
},
});
```
**Deliverable:** Team invitation mutation
**Status:** Ready for implementation
### Cycle 23: Create Invitation Acceptance Mutation
**Task:** Implement `acceptInvitation` mutation
**File to update:** `/backend/convex/mutations/workspace.ts`
```typescript
export const acceptInvitation = mutation({
args: {
token: v.string(),
},
handler: async (ctx, args) => {
// 1. Find invitation by token
// 2. Check if expired
// 3. Get or create user for email
// 4. Create member_of connection
// 5. Mark invitation as accepted
// 6. Log user_joined_group event
// 7. Return success
},
});
```
**Deliverable:** Invitation acceptance mutation
**Status:** Ready for implementation
### Cycle 24: Create Wallet Connection Mutation
**Task:** Implement `connectWallet` mutation
**File to update:** `/backend/convex/mutations/auth.ts`
```typescript
export const connectWallet = mutation({
args: {
address: v.string(),
signature: v.optional(v.string()),
},
handler: async (ctx, args) => {
// 1. Validate Ethereum address format
// 2. Optionally verify signature
// 3. Update creator.walletAddress
// 4. Update creator.walletVerified
// 5. Log wallet_connected event
// 6. Return success
},
});
```
**Deliverable:** Wallet connection mutation
**Status:** Ready for implementation
### Cycle 25: Create Skill Tagging Mutation
**Task:** Implement `addSkills` mutation
**File to update:** `/backend/convex/mutations/auth.ts`
```typescript
export const addSkills = mutation({
args: {
skills: v.array(v.string()),
},
handler: async (ctx, args) => {
// 1. Validate skills exist in taxonomy
// 2. Get or create knowledge items for each skill
// 3. Link creator to knowledge items
// 4. Update creator.expertise
// 5. Log thing_updated event
// 6. Return updated creator
},
});
```
**Deliverable:** Skill tagging mutation
**Status:** Ready for implementation
### Cycle 26: Create Onboarding Status Queries
**Task:** Implement queries for onboarding data
**File to create:** `/backend/convex/queries/onboarding.ts`
```typescript
export const getCurrentUser = query({ ... }) // Get current user + workspace
export const getOnboardingStatus = query({ ... }) // Get step + completion %
export const checkUsernameAvailable = query({ ... }) // Is username taken?
export const checkEmailExists = query({ ... }) // Does email exist?
export const getWorkspaceMembers = query({ ... }) // List workspace members
export const getPendingInvitations = query({ ... }) // List pending invites
export const getUserWorkspaces = query({ ... }) // List user's workspaces
```
**Deliverable:** All onboarding queries
**Status:** Ready for implementation
### Cycle 27: Create Email Templates
**Task:** Build email templates with Resend
**Files to create:**
- `/backend/convex/emails/welcome.email.tsx`
- `/backend/convex/emails/verify-email.email.tsx`
- `/backend/convex/emails/team-invite.email.tsx`
- `/backend/convex/emails/password-reset.email.tsx`
**Email Content:**
1. **Welcome:** "Welcome to ONE! Complete your profile to get started"
2. **Verify Email:** "Your 6-digit code: {code} (valid for 10 minutes)"
3. **Team Invite:** "You're invited to join {workspace}! {invite_link}"
4. **Password Reset:** "Reset your password: {reset_link} (valid for 30 minutes)"
**Deliverable:** All email templates
**Status:** Ready for implementation
### Cycle 28: Create Verification System
**Task:** Build verification code + token system
**File to create:** `/backend/convex/lib/verification.ts`
```typescript
export function generateVerificationCode(): string; // 6-digit code
export function generateVerificationLink(): string; // unique URL
export function verifyCode(code: string): boolean;
export function verifyLink(token: string): boolean;
export function rateLimit(email: string): boolean; // 5/hour
export function generateInvitationToken(): string; // for team invites
```
**Deliverable:** Verification utilities
**Status:** Ready for implementation
### Cycle 29: Set Up Rate Limiting
**Task:** Configure rate limiting for signup, verification
**Mutations to rate limit:**
- signUp (5 per IP per hour)
- sendVerificationEmail (5 per email per hour)
- inviteTeamMember (20 per workspace per day)
- connectWallet (5 per user per day)
**Deliverable:** Rate limiting configured
**Status:** Ready for implementation
### Cycle 30: Setup Complete - Backend Ready
**Task:** Final backend validation before frontend starts
**Checklist:**
- [ ] All mutations tested locally
- [ ] All queries working
- [ ] Email templates rendering
- [ ] Rate limiting active
- [ ] Events logging
- [ ] Schema validated
**Deliverable:** Backend production-ready
**Status:** ✅ Frontend can now start (parallel from Cycle 31)
---
## PHASE 3: FRONTEND COMPONENTS & PAGES (Cycle 31-50)
**Specialist:** Agent-Frontend
**Duration:** 3-4 days (20 cycles)
**Dependency:** ✅ Phase 2 (backend mutations/queries complete)
**Blocks:** API routes (Cycle 51-60)
### Cycle 31: Create SignupForm Component
**Task:** Build signup form with email/password + OAuth
**File to create:** `/web/src/components/onboarding/SignupForm.tsx`
**Features:**
- Email input (with validation)
- Password input (with strength meter)
- "I agree to terms" checkbox
- OAuth buttons (Google, GitHub, Discord)
- Error handling
- Loading state
- Success redirect
**Deliverable:** Working signup form component
**Status:** Ready for implementation
### Cycle 32: Create EmailVerification Component
**Task:** Build 6-digit code input
**File to create:** `/web/src/components/onboarding/EmailVerification.tsx`
**Features:**
- 6 separate input fields (auto-focus, auto-submit)
- "Check email" message
- Resend button (with 30s cooldown)
- Error messages
- Loading state
- Success animation
**Deliverable:** Email verification component
**Status:** Ready for implementation
### Cycle 33: Create ProfileForm Component
**Task:** Build profile completion form
**File to create:** `/web/src/components/onboarding/ProfileForm.tsx`
**Fields:**
- Avatar upload (preview, drag-drop)
- Display name
- Username (with slug preview: one.ie/@username)
- Bio (textarea, char counter)
- Niche selection (multi-select)
- Validation (unique username, bio < 500 chars)
- Save & Continue button
**Deliverable:** Profile form component
**Status:** Ready for implementation
### Cycle 34: Create WorkspaceSetup Component
**Task:** Build workspace creation UI
**File to create:** `/web/src/components/onboarding/WorkspaceSetup.tsx`
**Options:**
- Option A: "I'm solo" → Personal workspace
- Option B: "I manage a team" → Team workspace setup
- If team: Name workspace + invite members (email list)
- Save & Continue button
**Deliverable:** Workspace setup component
**Status:** Ready for implementation
### Cycle 35: Create WalletConnection Component
**Task:** Build optional wallet connection UI
**File to create:** `/web/src/components/onboarding/WalletConnection.tsx`
**Features:**
- Why wallet needed (explanation)
- "Connect Wallet" button
- Wallet options (MetaMask, Rainbow Kit, WalletConnect)
- "Skip for now" link
- Connected state (show address, verified checkmark, disconnect button)
- Uses wagmi/viem hooks
**Deliverable:** Wallet connection component
**Status:** Ready for implementation
### Cycle 36: Create SkillSelection Component
**Task:** Build skill/expertise tagging UI
**File to create:** `/web/src/components/onboarding/SkillSelection.tsx`
**Features:**
- Grouped skill tags (education, fitness, tech, etc)
- Multi-select (checkboxes)
- Add custom skill (free text)
- Save & Continue button
- Pre-populate from niche if selected
**Deliverable:** Skill selection component
**Status:** Ready for implementation
### Cycle 37: Create OnboardingTour Component
**Task:** Build interactive guided tour
**File to create:** `/web/src/components/onboarding/OnboardingTour.tsx`
**Steps:**
1. Welcome - Intro + features
2. Create content - Show editor
3. Manage team - Show team page
4. Monetize - Show X402 + pricing
5. Analytics - Show dashboard
6. What's next - Call to action
**Features:**
- Skip anytime
- Highlight UI elements
- Progress indicator (step X of 6)
- Next/Back buttons
- Show/hide on demand
**Deliverable:** Onboarding tour component
**Status:** Ready for implementation
### Cycle 38: Create OnboardingChecklist Component
**Task:** Build first-day quick wins checklist
**File to create:** `/web/src/components/onboarding/OnboardingChecklist.tsx`
**Checklist items:**
- Profile 80% complete
- Email verified
- Workspace created
- Team member invited (or solo)
- Wallet connected (encouraged)
- First skill added
**Features:**
- Progress bar (X/6 complete)
- Checkmarks + links to incomplete items
- Completion reward/badge
- Show next steps
**Deliverable:** Onboarding checklist component
**Status:** Ready for implementation
### Cycle 39: Create Onboarding Pages (Part 1)
**Task:** Build 4 Astro pages for onboarding flow
**Files to create:**
- `/web/src/pages/onboarding/index.astro` - Main entry
- `/web/src/pages/onboarding/signup.astro` - Signup form
- `/web/src/pages/onboarding/verify.astro` - Email verification
- `/web/src/pages/onboarding/profile.astro` - Profile form
**Features:**
- All `client:load` (interactive)
- Form validation
- Redirect on auth failure
- Progress indicator
- Mobile responsive
**Deliverable:** 4 onboarding pages
**Status:** Ready for implementation
### Cycle 40: Create Onboarding Pages (Part 2)
**Task:** Build remaining 4 Astro pages
**Files to create:**
- `/web/src/pages/onboarding/workspace.astro` - Workspace setup
- `/web/src/pages/onboarding/wallet.astro` - Wallet connection
- `/web/src/pages/onboarding/skills.astro` - Skill selection
- `/web/src/pages/onboarding/complete.astro` - Success + tour
**Features:**
- All `client:load`
- Progress tracking
- Skip options
- Redirect to dashboard when complete
- Mobile responsive
**Deliverable:** 4 more onboarding pages
**Status:** Ready for implementation
### Cycle 41: Create Team Management Page
**Task:** Build workspace settings page for team management
**File to create:** `/web/src/pages/workspace/settings/team.astro`
**Sections:**
- Members list (table)
- Invite new member form
- Pending invitations
- Member role/permissions modal
- Remove member button
**Actions:**
- Invite by email
- Change member role
- Remove member
- Resend invitation
- View activity
**Deliverable:** Team management page
**Status:** Ready for implementation
### Cycle 42: Create Avatar Upload Component
**Task:** Build avatar upload with preview
**File to create:** `/web/src/components/onboarding/AvatarUpload.tsx`
**Features:**
- Drag-drop + click upload
- Image preview
- Cropping (optional)
- Size validation (< 5MB)
- Format validation (jpg, png, webp)
- Upload to cloud storage
**Deliverable:** Avatar upload component
**Status:** Ready for implementation
### Cycle 43: Create Niche Selection Component
**Task:** Build niche/category multi-select
**File to create:** `/web/src/components/onboarding/NicheSelection.tsx`
**Features:**
- Grouped categories (fitness, education, tech, etc)
- Multi-select (checkboxes)
- Descriptions on hover
- Search/filter
- Pre-population logic
**Deliverable:** Niche selection component
**Status:** Ready for implementation
### Cycle 44: Create Loading States
**Task:** Add loading spinners + skeleton screens
**Components:**
- Form submit spinner
- Email sending indicator
- Page loading skeleton
- Image upload progress
**Deliverable:** Loading components
**Status:** Ready for implementation
### Cycle 45: Create Error Handling
**Task:** Build error display + recovery UI
**Features:**
- Error toast notifications
- Field-level error messages
- Retry buttons
- Clear error messaging
- Helpful recovery steps
**Deliverable:** Error handling components
**Status:** Ready for implementation
### Cycle 46: Create Success Animations
**Task:** Add celebration animations
**Animations:**
- Email verified checkmark
- Workspace created success
- Profile completed celebration
- Full onboarding completion confetti
**Deliverable:** Success animation components
**Status:** Ready for implementation
### Cycle 47: Create Mobile Responsive Design
**Task:** Optimize all components for mobile
**Checklist:**
- [ ] All forms mobile-friendly
- [ ] Avatar upload works on mobile
- [ ] Code input optimized for mobile keyboard
- [ ] Buttons large enough (48px min)
- [ ] Text readable on small screens
- [ ] No horizontal scroll
**Deliverable:** Mobile-optimized components
**Status:** Ready for implementation
### Cycle 48: Create Accessibility Features
**Task:** Add WCAG 2.1 AA compliance
**Features:**
- Proper labels + aria-labels
- Keyboard navigation
- Color contrast (4.5:1 minimum)
- Focus indicators
- Reduced motion support
- Screen reader friendly
**Deliverable:** Accessible components
**Status:** Ready for implementation
### Cycle 49: Create Dark Mode Support
**Task:** Add dark theme support
**Features:**
- Color scheme aware
- Stored preference
- System preference detection
- Toggle in settings
**Deliverable:** Dark mode theme
**Status:** Ready for implementation
### Cycle 50: Frontend Complete - Ready for API
**Task:** Final frontend validation
**Checklist:**
- [ ] All 8 onboarding pages working
- [ ] Team management page working
- [ ] All components rendering
- [ ] Mobile responsive
- [ ] Accessibility compliant
- [ ] Ready to connect to API routes
**Deliverable:** Production-ready frontend
**Status:** ✅ Ready for API routes (Cycle 51)
---
## PHASE 4: API ROUTES & INTEGRATION (Cycle 51-80)
**Specialist:** Agent-Integration / Agent-Backend
**Duration:** 3-4 days (30 cycles)
**Dependency:** ✅ Phase 2 (backend) + Phase 3 (frontend) complete
**Blocks:** Testing (Cycle 81-90)
### Cycle 51-60: Create API Routes
**Task:** Build HTTP endpoints connecting frontend to backend
**Routes to create:**
```
/api/auth/signup POST Register new user
/api/auth/verify-email POST Verify email with code
/api/auth/resend-verification POST Resend verification code
/api/auth/login POST Login (email/password)
/api/profile/get GET Get current user profile
/api/profile/update POST Update profile
/api/profile/upload-avatar POST Upload avatar image
/api/workspace/create POST Create workspace
/api/workspace/list GET List user's workspaces
/api/workspace/[id]/get GET Get workspace details
/api/workspace/[id]/update POST Update workspace
/api/team/invite POST Invite team member
/api/team/accept-invitation POST Accept invite (with token)
/api/team/[workspace]/members GET List workspace members
/api/team/[workspace]/pending GET List pending invitations
/api/team/[workspace]/role POST Change member role
/api/team/[workspace]/remove POST Remove team member
/api/wallet/connect POST Connect crypto wallet
/api/wallet/verify POST Verify wallet signature
/api/skills/add POST Add skills to creator
/api/skills/list GET Get available skills
/api/onboarding/status GET Get onboarding progress
/api/onboarding/step POST Update onboarding step
```
Each route:
- Validates input
- Calls Convex mutation/query
- Handles errors
- Returns JSON
- Logs events
**Deliverable:** All API routes functional
**Status:** Ready for implementation
### Cycle 61-70: Email System Setup
**Task:** Configure email sending with Resend
**Setup:**
- Resend API key configured
- Email templates created
- Verification code system
- Rate limiting (prevent spam)
- Tracking (opens, clicks)
**Emails sent:**
1. Welcome email (after signup)
2. Verification code (6-digit)
3. Team invitation
4. Password reset
5. Onboarding reminder (if abandoned)
**Deliverable:** Email system ready
**Status:** Ready for implementation
### Cycle 71-80: Integration Testing
**Task:** Test frontend → API → backend → database flow
**Test scenarios:**
1. Signup flow (email + password)
2. Email verification
3. Profile completion
4. Workspace creation
5. Team invitation + acceptance
6. Wallet connection
7. Skill tagging
8. Full journey (signup to dashboard)
**Each scenario:**
- Test happy path
- Test error cases
- Test validation
- Test rate limiting
- Verify events logged
- Verify database state
**Deliverable:** Integration tests passing
**Status:** Ready for implementation
---
## PHASE 5: TESTING & QUALITY (Cycle 81-90)
**Specialist:** Agent-Quality
**Duration:** 2-3 days (10 cycles)
**Dependency:** ✅ Phase 4 complete
**Blocks:** Documentation (Cycle 91-100)
### Cycle 81-82: Unit Tests (Backend)
**Task:** Test mutations, queries, services in isolation
**Coverage:**
- Onboarding service (all methods)
- Verification system
- Rate limiting
- Email generation
**Target:** 90%+ coverage
**Deliverable:** Unit tests passing
**Status:** Ready for implementation
### Cycle 83-84: Unit Tests (Frontend)
**Task:** Test React components in isolation
**Coverage:**
- SignupForm validation
- EmailVerification logic
- ProfileForm validation
- WorkspaceSetup routing
- All form components
**Target:** 85%+ coverage
**Deliverable:** Frontend unit tests passing
**Status:** Ready for implementation
### Cycle 85-86: Integration Tests
**Task:** Test full signup → dashboard flow
**Scenarios:**
1. Complete signup in < 10 minutes
2. Verify email delivery timing
3. Workspace creation triggers event
4. Team invitation generates token
5. Skill tagging links to knowledge
**Deliverable:** Integration tests passing
**Status:** Ready for implementation
### Cycle 87-88: E2E Tests
**Task:** Test full user journey in browser
**Scenarios:**
1. New user signup → dashboard access
2. Team member invitation → acceptance → join workspace
3. Wallet connection flow
4. Onboarding checklist completion
**Tools:** Playwright or Cypress
**Deliverable:** E2E tests passing
**Status:** Ready for implementation
### Cycle 89: Security + Accessibility Audit
**Task:** Verify security + accessibility compliance
**Security checks:**
- SQL injection prevention
- XSS protection
- CSRF tokens
- Password hashing
- Email verification required before action
**Accessibility checks:**
- WCAG 2.1 AA compliance
- Keyboard navigation
- Screen reader testing
- Color contrast
- Focus management
**Deliverable:** Audit report + fixes
**Status:** Ready for implementation
### Cycle 90: Performance Audit
**Task:** Verify performance targets met
**Metrics:**
- Page load: < 2s
- Form submit: < 1s
- Email delivery: < 30s
- Mobile performance: 70%+ of desktop
- Lighthouse score: > 85
**Deliverable:** Performance report
**Status:** Ready for implementation
---
## PHASE 6: DEPLOYMENT & DOCUMENTATION (Cycle 91-100)
**Specialist:** Agent-Ops + Agent-Documenter
**Duration:** 1-2 days (10 cycles)
**Dependency:** ✅ Phase 5 complete
### Cycle 91-92: Create User Documentation
**Files:**
- `/docs/getting-started.md` - For new creators
- `/docs/onboarding-guide.md` - Step-by-step walkthrough
- `/docs/team-management.md` - How to manage team
- `/docs/troubleshooting.md` - Common issues + fixes
**Deliverable:** User guides complete
**Status:** Ready for implementation
### Cycle 93-94: Create API Documentation
**Files:**
- `/docs/api/auth.md` - Auth endpoints
- `/docs/api/profile.md` - Profile endpoints
- `/docs/api/workspace.md` - Workspace endpoints
- `/docs/api/team.md` - Team endpoints
- `/docs/api/errors.md` - Error codes + meanings
**Content:**
- Endpoint description
- Request/response examples
- Curl examples
- Error codes
- Rate limits
**Deliverable:** API docs complete
**Status:** Ready for implementation
### Cycle 95: Create Developer Setup Guide
**File:** `/docs/developer-setup.md`
**Content:**
- Clone repo
- Install dependencies
- Environment variables
- Run dev server
- Run tests
- Deploy to staging
**Deliverable:** Setup guide complete
**Status:** Ready for implementation
### Cycle 96: Create Deployment Checklist
**File:** `/DEPLOYMENT.md`
**Checklist:**
- [ ] All tests passing
- [ ] Security audit passed
- [ ] Performance targets met
- [ ] Accessibility compliant
- [ ] Staging environment tested
- [ ] Monitoring configured
- [ ] Rollback plan ready
- [ ] Customer notification sent
- [ ] Analytics tracking active
**Deliverable:** Deployment ready
**Status:** Ready for implementation
### Cycle 97-98: Deploy to Production
**Task:** Deploy backend + frontend to production
**Steps:**
1. Deploy backend to Convex Cloud
2. Deploy frontend to Cloudflare Pages
3. Run smoke tests in production
4. Monitor for errors
5. Track key metrics
**Deliverable:** Live production deployment
**Status:** Ready for implementation
### Cycle 99: Monitor + Optimize
**Task:** Monitor production for issues
**Metrics to track:**
- Signup completion rate
- Email delivery rate
- API error rate
- Page load performance
- User feedback
**Optimizations:**
- Fix any performance issues
- Improve UX based on usage
- Fix any bugs found
**Deliverable:** Monitoring active
**Status:** Ready for implementation
### Cycle 100: Wave 1 Complete - Lessons Learned
**Task:** Document lessons for Wave 2
**Document:**
- What worked well
- What was harder than expected
- What would improve next time
- Infrastructure learnings
- Team productivity notes
**Deliverable:** Lessons learned document
**Status:** Ready for implementation
---
## Parallel Execution Strategy
Some phases can run **simultaneously** (not sequentially):
```
Timeline:
Day 1-2: Cycle 1-10 (Foundation)
└─ All specialists align on ontology
Day 3: Cycle 11-20 (Backend schema)
└─ Only backend specialist
Day 4-5: Cycle 21-30 (Backend mutations + Cycle 31-50 (Frontend components)
└─ Backend + Frontend IN PARALLEL
├─ Backend: Finish mutations/queries
└─ Frontend: Build components
Day 6: Cycle 51-70 (API routes + Email)
└─ Integration specialist starts
└─ Backend: API route creation
└─ Frontend: Component completion
Day 7: Cycle 71-80 (Integration testing)
└─ All work tested together
Day 8: Cycle 81-90 (Quality + Security)
└─ Quality specialist validates
Day 9-10: Cycle 91-100 (Deployment + Docs)
└─ Deploy to production
└─ Create user/API documentation
TOTAL: 10 days (more like 1.5 weeks with buffers)
```
**Key:** Backend must be ready by Day 6 before API routes. Frontend must be ready by Day 5 for API integration.
---
## Specialist Assignments
### Agent-Backend (Cycle 11-30 + 51-70)
**40 cycles total**
- Schema updates (Cycle 11-16)
- Onboarding service (Cycle 17)
- All mutations (Cycle 18-25)
- All queries (Cycle 26)
- Email templates (Cycle 27)
- Verification system (Cycle 28)
- Rate limiting (Cycle 29)
- API route creation (Cycle 51-60)
- Email system setup (Cycle 61-70)
### Agent-Frontend (Cycle 31-50)
**20 cycles total**
- All 8 onboarding components (Cycle 31-38)
- 8 onboarding pages (Cycle 39-40)
- Team management page (Cycle 41)
- Avatar upload (Cycle 42)
- Niche selection (Cycle 43)
- Loading states (Cycle 44)
- Error handling (Cycle 45)
- Success animations (Cycle 46)
- Mobile responsive (Cycle 47)
- Accessibility (Cycle 48)
- Dark mode (Cycle 49)
- Final validation (Cycle 50)
### Agent-Quality (Cycle 81-90)
**10 cycles total**
- Backend unit tests (Cycle 81-82)
- Frontend unit tests (Cycle 83-84)
- Integration tests (Cycle 85-86)
- E2E tests (Cycle 87-88)
- Security + accessibility audit (Cycle 89)
- Performance audit (Cycle 90)
### Agent-Ops / Agent-Documenter (Cycle 91-100)
**10 cycles total**
- User documentation (Cycle 91-92)
- API documentation (Cycle 93-94)
- Developer setup (Cycle 95)
- Deployment checklist (Cycle 96)
- Production deployment (Cycle 97-98)
- Monitoring (Cycle 99)
- Lessons learned (Cycle 100)
### Agent-Director (Orchestrator)
**Throughout**
- Progress tracking
- Blocker resolution
- Specialist coordination
- Event logging
- Completion validation
---
## Success Criteria for Wave 1 Complete
All of these must be ✅ before Wave 1 is marked done:
- ✅ User can register with email + password
- ✅ OAuth signup works (Google, GitHub, Discord)
- ✅ Email verification working (code sent + verified)
- ✅ Profile form complete + avatar upload
- ✅ Workspace creation working
- ✅ Team member invitations working (send + accept)
- ✅ Wallet connection optional but functional
- ✅ Skills/expertise tagging working
- ✅ Onboarding status tracked (events logged)
- ✅ 80%+ of test users complete flow
- ✅ Average time < 15 minutes
- ✅ Mobile-responsive (70%+ desktop conversion)
- ✅ WCAG 2.1 AA accessibility
- ✅ New creator can access dashboard
- ✅ Team features tested + working
- ✅ Complete audit trail (all events logged)
- ✅ API documented
- ✅ User guides created
- ✅ Deployment checklist complete
- ✅ Live in production
---
## Risk Mitigation
**Potential blockers & solutions:**
| Risk | Likelihood | Impact | Mitigation |
| ---------------------------------- | ---------- | ------ | -------------------------------------- |
| Better Auth integration complexity | Medium | High | Have 2 backend specialists ready |
| Email delivery delays | Low | Medium | Use Resend sandbox for testing |
| Rate limiting issues | Low | Medium | Start simple, iterate based on testing |
| Mobile UI responsive issues | Medium | Medium | Test early + often on real devices |
| Database performance | Low | Medium | Index optimization, pre-optimize |
| Security vulnerabilities | Low | High | Early security audit, follow OWASP |
---
## Estimated Resource Requirements
| Resource | Quantity | Days |
| ----------------------- | -------- | ------------------ |
| Backend Specialist | 1 | 10 days |
| Frontend Specialist | 1 | 10 days |
| Quality Specialist | 1 | 3 days |
| Designer/Documenter | 1 | 5 days |
| Orchestrator (Director) | 1 | 10 days |
| **Total Person-Days** | **5** | **38 person-days** |
**Actual Calendar Time:** 10-12 days (due to parallelization)
---
**Status:** Ready for implementation
**Approved:** Engineering Director
**Start Date:** Immediate (Cycle 1)
**Expected Completion:** +10-12 calendar days