How We Onboard New Client Projects in One Week

The first week of a new project sets the tone for everything that follows. Move too slowly and momentum stalls before the first commit. Move too fast and you build on a shaky foundation — wrong assumptions, missing infrastructure, unclear priorities.

We have onboarded dozens of client projects over five years. The process has evolved through trial, error, and a lot of wasted time early on. What we have now is a repeatable system that takes a signed contract and produces a running codebase, a configured CI pipeline, a working staging environment, and a clear two-week sprint plan — all within five business days.

Here is exactly how we do it.

Day 1: Kickoff call and discovery

The kickoff call is not a formality. It is the most important meeting of the entire engagement. We run it for 90 minutes to two hours with every stakeholder who will be involved in the project.

The agenda:

Product context (30 minutes). What does the product do? Who are the users? What problem does it solve? We need to understand the “why” before we touch any “how.” This is where clients tell us what they actually care about — and often, what they say matters most is different from what the spec document emphasizes.

Scope walkthrough (30 minutes). We go through the feature list or spec line by line. Not to debate scope — that happened during the proposal phase — but to make sure everyone has the same understanding of what each feature means. “User management” means different things to different people. We pin down specifics: invite-only or self-signup? Role-based access or flat permissions? SSO or email/password?

Technical constraints (15 minutes). Existing systems we need to integrate with, compliance requirements, performance targets, deployment restrictions. If the client has an existing codebase, we get access during the call and review it together.

Communication setup (15 minutes). We agree on communication channels (Slack, email, or both), meeting cadence (weekly or biweekly demos), and who the primary contact is for day-to-day decisions. Decision bottlenecks are the number one cause of project delays. We establish early who can say “yes” without calling a meeting.

By the end of day one, we have a shared Notion document with the full scope, a Slack channel, and access to every system we need.

Team collaborating during a project kickoff meeting

Day 2: Repository scaffolding and tooling

Day two is all engineering. We set up the project foundation based on what we learned in the kickoff call.

Our standard stack for new projects is Astro or SvelteKit for the frontend, Supabase for the backend, and Vercel or Cloudflare for hosting. The specific choice depends on the project. Content-heavy sites get Astro. Application-heavy products get SvelteKit. For a deeper look at how we make that call, see our post on Astro vs Next.js.

The scaffolding script we run:

# Initialize the project with our template
npx degit threshline/project-template client-project
cd client-project

# Install dependencies
npm install

# Set up environment files
cp .env.example .env.local

# Initialize Supabase
npx supabase init
npx supabase start

# Create the initial database schema
npx supabase db push

# First commit
git init
git add .
git commit -m "chore: initial project scaffold"

The template includes our standard configuration for:

TypeScript with strict mode enabled
Tailwind CSS with our design token structure (see our post on color systems for product design)
ESLint and Prettier with our house rules
Vitest for unit testing
Playwright for E2E testing (our default, as discussed in Playwright vs Cypress)
Husky for pre-commit hooks (type check, lint, format)

The repo gets pushed to GitHub under the client’s organization or our organization, depending on the agreement. Branch protection goes on immediately — no direct pushes to main, all changes through PRs, at least one review required.

// Standard project structure
src/
  components/     // UI components
  layouts/        // Page layouts
  pages/          // Routes
  lib/            // Business logic, utilities, API clients
  styles/         // Global styles, design tokens
  types/          // TypeScript type definitions
supabase/
  migrations/     // Database migrations
  functions/      // Edge functions
  seed.sql        // Development seed data
e2e/              // Playwright E2E tests
tests/            // Unit tests (mirrors src/ structure)

Every project gets the same structure. Not because we are rigid, but because consistency across projects means any of our four engineers can pick up any project without orientation time. When one person is on vacation and a production bug comes in, someone else can fix it without a codebase tour.

Day 3: CI/CD pipeline and environments

By day three, we have code. Now it needs to deploy automatically and reliably.

Our standard GitHub Actions workflow:

# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: 'npm'

      - run: npm ci
      - run: npm run typecheck
      - run: npm run lint
      - run: npm run test

  e2e:
    runs-on: ubuntu-latest
    needs: quality
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: 'npm'

      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npm run build
      - run: npx playwright test
        env:
          CI: true

      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report
          path: playwright-report/

We set up three environments:

Local development runs against a local Supabase instance with seed data. Every engineer gets an isolated database. No stepping on each other’s data.

Staging deploys automatically from the develop branch. It connects to a Supabase staging project with realistic (but non-production) data. Clients review features here before they go to production.

Production deploys from main via a merge from develop. No direct pushes, no manual deployments. The only way code reaches production is through a reviewed PR that passes CI.

Environment variables go into Vercel or Cloudflare’s dashboard, never committed to the repo. We use a .env.example file with placeholder values so developers know what variables are needed without exposing actual secrets.

For more detail on our CI setup, see our post on GitHub Actions CI/CD for small teams.

Developer setting up a new project workspace with tools and documentation

Day 3-4: Design review and token setup

If the client has designs (Figma, Sketch, or even annotated screenshots), we do a thorough design review on day three or four. If they do not have designs, we establish a minimal design direction using our token system.

The design review covers:

Component inventory. We list every unique component visible in the designs — buttons, cards, forms, modals, navigation, tables. This becomes the component build list for the first sprint.

Design token extraction. We pull colors, typography, spacing, and border radius values from the designs and map them to our token structure:

:root {
  /* Typography — extracted from Figma */
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;

  --text-xs: 0.75rem;
  --text-sm: 0.875rem;
  --text-base: 1rem;
  --text-lg: 1.125rem;
  --text-xl: 1.25rem;
  --text-2xl: 1.5rem;
  --text-3xl: 1.875rem;

  /* Spacing — based on 4px grid */
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-3: 0.75rem;
  --space-4: 1rem;
  --space-6: 1.5rem;
  --space-8: 2rem;
  --space-12: 3rem;
  --space-16: 4rem;

  /* Radii */
  --radius-sm: 0.25rem;
  --radius-md: 0.5rem;
  --radius-lg: 0.75rem;
  --radius-full: 9999px;
}

Responsive strategy. We confirm breakpoints, identify components that need mobile-specific layouts, and flag any designs that will not work on small screens. Better to raise this on day four than discover it during sprint two.

Accessibility review. We check color contrast ratios, identify components that need ARIA attributes, and note any interactive patterns that need keyboard support. This is not exhaustive — it is a first pass to catch obvious issues before we start building.

When we onboarded JustTheRip, the digital pack-opening platform, the design review caught that the card reveal animation would cause motion sickness issues without a reduced-motion alternative. We added that to the sprint plan before a single component was built.

Day 4-5: Database schema and seed data

With the scope pinned down and designs reviewed, we design the initial database schema. This is not the final schema — it will evolve. But it needs to be solid enough to support the first sprint’s features.

-- supabase/migrations/001_initial_schema.sql

-- Enable RLS on all tables from the start
alter default privileges in schema public
  grant select, insert, update, delete on tables to authenticated;

-- Users profile (extends Supabase auth.users)
create table public.profiles (
  id uuid primary key references auth.users(id) on delete cascade,
  full_name text not null,
  avatar_url text,
  role text not null default 'member' check (role in ('owner', 'admin', 'member')),
  created_at timestamptz not null default now(),
  updated_at timestamptz not null default now()
);

alter table public.profiles enable row level security;

create policy "Users can read own profile"
  on public.profiles for select
  using (auth.uid() = id);

create policy "Users can update own profile"
  on public.profiles for update
  using (auth.uid() = id);

We always enable Row Level Security from the first migration. Bolting it on later is painful and error-prone. For our approach to RLS patterns, see our post on Supabase Row Level Security patterns.

Alongside the schema, we write seed data:

-- supabase/seed.sql
-- Realistic seed data for development

-- Note: auth users are created via Supabase dashboard or CLI
-- These profiles reference those auth users

insert into public.profiles (id, full_name, role) values
  ('d0e1f2a3-b4c5-6789-abcd-ef0123456789', 'Test Admin', 'owner'),
  ('a1b2c3d4-e5f6-7890-abcd-ef0123456789', 'Test Member', 'member');

Good seed data is underrated. Every engineer working on the project should be able to run npx supabase db reset and have a fully populated local database in seconds. No manual setup, no shared dev databases, no “works on my machine” problems.

Team members welcoming a new colleague aboard a shared project

Day 5: Sprint planning and first commit

By Friday, we have a running codebase, a CI pipeline, staging and production environments, a design token system, and a database schema. Now we plan the first sprint.

We use two-week sprints. The first sprint for any project focuses on three things:

Authentication and user management. The foundation that almost every other feature depends on. Sign up, log in, profile management, role assignment. We get this right first because getting it wrong has cascading effects.

Core navigation and layout. The application shell — sidebar, header, routing, responsive layout. This is the skeleton that every feature page lives inside.

One user-facing feature. Not the most complex feature. The most demonstrable one. Something the client can interact with at the end of sprint one and think, “This is real.” For MindHyv, it was the booking calendar. For LancerSpace, it was the client list. For Trackelio, it was the feedback form.

The sprint plan goes into Linear (our project management tool) as tickets with clear acceptance criteria. Each ticket is small enough to complete in a day or two. Large features are broken into multiple tickets.

By end of day five, the first ticket is usually in progress. The first meaningful PR — not just scaffolding, but actual product code — lands within the first week.

Why this process matters

The onboarding week is not just about speed. It is about building trust.

When clients see a running staging environment five days after signing the contract, it signals competence. When they see a CI pipeline catching errors before code reaches production, it signals professionalism. When they see a clear sprint plan with specific deliverables and dates, it signals organization.

The opposite — three weeks of “setting things up” with nothing to show — erodes trust before the real work even starts. We have heard this from clients who came to us after bad experiences with other teams: they waited weeks for the first deploy and months for the first usable feature.

Our onboarding process is documented, repeatable, and battle-tested across every project in our portfolio. It takes the chaos out of project starts and replaces it with a system that works every time.

For more on how we manage projects after the onboarding phase, see our post on how we scope software projects and weekly demos in software development.

If you have a project ready to start and want to see how fast we can get it moving, reach out at [email protected]. We will have you from signed contract to first commit before the week is out.