Web Designer Onboarding & Handoff

SOP: Web Designer Onboarding & Handoff

Last Updated: 2026-04-30 Version: 1.1 (desktop app workflow) Tier: Onboarding (mandatory before first edit to any client repo)

---

Purpose

Brings a new web designer or contractor up to speed on the Tekton Growth web platform — Astro on Cloudflare Pages with GitHub source control. Uses the Claude Code desktop app as the primary interface, so you talk to Claude in plain English instead of typing terminal commands.

The single most important rule on day one:

Never push directly to main. Always work on a branch, test the change in your browser, then merge to main via a Pull Request.

A push to main deploys to the live client website in ~30 seconds. There is no staging server, no “preview” gate. If you push broken code to main, the client’s site is broken.

When to Use:

• Onboarding a new web designer, contractor, or internal team member
• Refresher when someone hasn’t touched a repo in 60+ days

Owner: Nick (executes invites + role assignments), new team member (works through this doc) Timeline: ~90 minutes for full setup. Re-readable as reference whenever needed.

Working with Claude on this SOP

The fastest way through this SOP is to paste it into Claude Code (desktop app) and tell Claude what you need:

• “Run this SOP for me on the Leon’s Landscaping clone.”
• “Walk me through this SOP step by step. Don’t move on until I confirm each step.”

If you hit a snag — a command fails, a result looks wrong, something doesn’t match the doc — just describe the issue in plain English: “the dev server won’t start, here’s the error” or “the diff doesn’t show what I expected, can you investigate?”

Don’t micromanage Claude. Describe the goal and the problem. Claude figures out the path. Trying to dictate every sub-step slows everything down and produces worse output than just letting it work.

---

1. The system overview

Client websites migrated off their original CMSes (Squarespace, WP/Elementor, GHL, Topline Pro, custom HTML) onto a unified stack:

flowchart LR
  You[You editing<br/>in Claude Code] -->|push to main| GitHub[GitHub repo<br/>Tektongrowth/&lt;client&gt;]
  GitHub -->|auto-deploy<br/>~30s| CFPages[Cloudflare Pages]
  CFPages -->|static HTML +<br/>functions| CDN[Cloudflare<br/>Global CDN]
  CDN -->|serves| Visitor((Site visitor))
  Forms[GHL form embed] -.->|leads| GHL[GoHighLevel<br/>CRM]

  style You fill:#2563eb,color:#fff
  style GitHub fill:#0f172a,color:#fff
  style CFPages fill:#f97316,color:#fff
  style CDN fill:#f97316,color:#fff
  style GHL fill:#1e40af,color:#fff

Layer	Tool	Purpose
Framework	Astro	Builds static + serverless sites
Source code	GitHub (Tektongrowth org)	Version control, source of truth
Hosting	Cloudflare Pages (free tier)	Global CDN, auto-deploy on push to main
Editing	Claude Code desktop app	AI-assisted editor — talk to it in English
Domain & DNS	Cloudflare DNS (post-cutover)	Manages where the domain points
Forms	GoHighLevel embeds	Lead capture, routes to client’s CRM

Where each client lives:

• GitHub: github.com/Tektongrowth/<client-slug>
• Test URL: <client-slug>.pages.dev (noindex protected)
• Production URL: client’s actual domain (post-cutover)

Push to main = deploy to production. Treat every commit on main as live.

---

2. Account setup

2.1 — GitHub

1. Create account at https://github.com/join with real name + work email
2. Enable 2-factor authentication (Settings → Password and authentication → Two-factor authentication). Mandatory.
3. Send Nick your GitHub username
4. Nick adds you as a Member of the Tektongrowth organization
5. Accept the email invite

2.2 — Claude Code desktop app

This is your main editor.

1. Sign up at https://claude.ai (Pro plan recommended — $20/month)
2. Download the desktop app: https://claude.ai/download (Mac or Windows)
3. Install + open the app, sign in with your Claude account
4. The app lets you have a chat conversation with Claude that has full access to your computer — file system, terminal, browser. You give it instructions in English; it does the work.

You never have to memorize git commands. You’ll tell Claude things like “create a branch and update the phone number on the contact page” and it handles the steps.

2.3 — Run the toolkit installer (one time only)

Tekton Growth ships every web designer with a private toolkit repo that contains every skill, script, and memory file you need. One command installs everything.

Open the Terminal app (built into your Mac, find it via Cmd+Space → “Terminal”) and paste these two commands:

git clone https://github.com/Tektongrowth/tekton-toolkit-web-designer.git ~/Projects/tekton-toolkit
cd ~/Projects/tekton-toolkit && ./setup.sh

The setup script handles:

• Homebrew, Node.js, Git, GitHub CLI, Wrangler, Python (skips anything already installed)
• GitHub auth (interactive — follow the browser prompt when it asks)
• Copies all 20 web designer skills to ~/.claude/skills/
• Copies the global Tekton Growth CLAUDE.md to ~/.claude/CLAUDE.md
• Copies the shared memory files to your Claude Code memory folder
• Symlinks helper scripts to ~/Projects/scripts/
• Prints a checklist of remaining manual steps

When the script finishes, work through the printed checklist. You’re done with the terminal after this. Everything from now on goes through Claude Code desktop.

To pull updates later (when Nick adds a new skill or updates a memory file):

cd ~/Projects/tekton-toolkit && ./update.sh

That’s it.

2.4 — Cloudflare access

Send Nick your email. He invites you with the Cloudflare Pages — Edit role.

1. Confirm email invite
2. Set up 2FA at https://dash.cloudflare.com/profile/authentication
3. You’ll see Tekton Growth account in the dashboard
4. Bookmark https://dash.cloudflare.com — you’ll use it to:
   • Watch deployments succeed/fail
   • Manage DNS during cutover
   • Check site analytics

You don’t need a personal Cloudflare API token. Claude Code will use the one Nick gives you.

---

3. Cloning your first client repo (using Claude Code)

When you’re ready to work on a client site, open Claude Code desktop and tell it:

Clone the leons-landscaping repo from the Tektongrowth GitHub org. Put it in ~/Projects/clients/. Then cd into it and run npm install.

Claude will:

1. Run the gh repo clone Tektongrowth/leons-landscaping command
2. Move into the folder
3. Install dependencies

When it finishes, you have a working local copy ready to edit.

For each new client repo you start working on, you’ll do this once.

---

4. The branch → test → merge workflow

This is the most important section. Read it twice.

Why it matters

main = the live website. Every push to main deploys in ~30 seconds. There is no staging URL. So:

• Push broken HTML to main → client’s site is broken until you fix it
• Push a typo → every visitor sees the typo until you fix it
• Push a CSS bug that hides their phone number → they lose leads until you fix it

The fix: never edit main directly. Always create a branch, test the change in your browser, then merge via a Pull Request.

What you say to Claude vs. what Claude does

You’ll prompt Claude in plain English. Claude runs the actual git/npm commands behind the scenes. Your job is to (a) give clear instructions and (b) verify the result in your browser before merging.

The workflow at a glance

flowchart TD
  Start([Client request:<br/>change phone number]) --> Pull[Tell Claude:<br/>pull latest main]
  Pull --> Branch[Tell Claude:<br/>create branch fix/phone-number]
  Branch --> Edit[Tell Claude what to change<br/>review the diff]
  Edit --> Server[Tell Claude:<br/>start dev server]
  Server --> Browser{Open localhost:4321<br/>in your browser<br/>does it work?}
  Browser -->|No| Edit
  Browser -->|Yes| Stop[Tell Claude:<br/>stop server, commit, push]
  Stop --> PR[Open PR<br/>self-review the diff]
  PR --> Merge{Diff looks right?}
  Merge -->|No| Edit
  Merge -->|Yes| Live[Merge to main<br/>auto-deploys in ~30s]
  Live --> Verify[Open production URL<br/>incognito window<br/>verify live]
  Verify --> Done([Done. Log the change.])

  style Browser fill:#fbbf24,color:#000
  style Merge fill:#fbbf24,color:#000
  style Live fill:#22c55e,color:#fff
  style Done fill:#22c55e,color:#fff

The two diamonds are your two human-judgment moments: (1) does the change actually work in the browser? and (2) does the GitHub diff show only what you intended? Everything else Claude does for you.

The full workflow — example

A client wants their phone number updated on Leon’s site.

Step 1 — Tell Claude to start a fresh branch

In Claude Code desktop, prompt:

Working in the leons-landscaping repo. Pull the latest from main, then create a new branch called fix/leons-phone-number.

Claude pulls latest main, creates the branch, switches to it. Confirm in the chat output that it succeeded.

Step 2 — Tell Claude what to change

Update Leon’s phone number across the site from (513) 555-0000 to (513) 555-1234. Check the header, footer, contact page, and any schema/meta tags. Show me the diff before saving.

Claude finds every occurrence, shows you the diff (the before/after for each line), and asks for confirmation. Read the diff. Make sure it’s only changing what you intended.

If it looks right, tell Claude “go ahead, save the changes.”

Step 3 — Test in your browser (critical step)

Tell Claude:

Start the local dev server.

Claude runs npm run dev. It’ll print a URL, usually http://localhost:4321.

Open that URL in your browser. Click around. Look at the change. Check:

• The page where the change should appear
• Neighboring pages
• Mobile view (resize your browser window narrow)

This is the step you cannot skip. Claude is good but not perfect. Your job is to look at the actual website and confirm the change works.

If the change is wrong: tell Claude what’s wrong, it’ll fix and you re-test.

If the change is right: tell Claude “stop the dev server.”

Step 4 — Tell Claude to commit and push the branch

Commit these changes with message “fix: update Leon’s phone number to (513) 555-1234” and push the branch to GitHub.

Claude runs git add, git commit, git push. Confirms in chat.

Step 5 — Open a Pull Request

Open a Pull Request on GitHub for this branch. Title it “fix: Leon’s phone number”. In the description, say what changed and why.

Claude runs gh pr create and gives you the URL of the new PR.

Click the URL. The PR opens on GitHub in your browser.

Step 6 — Self-review on GitHub

The PR page shows you exactly what’s changing. Click the Files changed tab. Read every line. Check:

• Only files you intended to change are in the diff
• No accidental changes to other files
• No .env or secrets committed

Step 7 — Merge to main

If the diff looks right, click Merge pull request → Confirm merge.

This kicks off the Cloudflare Pages deployment. Wait ~30 seconds.

Step 8 — Verify on the live site

Open the production URL (or the test pages.dev URL if pre-cutover) in a fresh incognito browser window (so you bypass cache). Confirm your change is live.

If the change isn’t visible:

• Did the deploy succeed? Check the Cloudflare Pages dashboard
• Hard refresh (Cmd+Shift+R)
• Did Claude actually push? Tell Claude “verify the latest commit is on origin/main”

Step 9 — Tell Claude to clean up

Switch back to main, pull latest, and delete the local fix/leons-phone-number branch.

Claude tidies up. Repo is clean for the next change.

Branch protection rules (Nick configures)

The main branch on every client repo is locked down:

• Cannot push directly (must go through PR)
• PRs require 1 approval (you can self-approve)
• PRs must pass build status check

If Claude (or anyone) tries to push to main directly, GitHub rejects it. That’s the safety net.

When you mess up

You will. Here’s what to do — you can tell Claude any of these in plain English:

Pushed broken code to a branch (not main): just tell Claude “undo the last commit on this branch and let me try again” or “fix this issue and commit again.”

Pushed broken code to main:

• Don’t panic.
• Tell Claude “revert the last commit on main and push immediately.”
• Cloudflare auto-deploys the previous version in 30 seconds
• Tell Nick what happened so we can debrief

Can’t figure out what broke: tell Nick immediately. The Cloudflare Pages dashboard shows historical deployments — we can roll back to any prior version with two clicks.

---

5. Common edit tasks (all done by prompting Claude)

Update copy / text on a page

On the Leon’s homepage, change the headline “Welcome” to “Greater Cincinnati Landscaping Experts.” Show me the diff.

Swap a photo

Replace the hero image on the Leon’s homepage with this file: ~/Downloads/new-hero.jpg. Compress it to under 200 KB first. Update the alt text to “Leon’s crew installing pavers in Hamilton County.”

Update business hours / contact info

Update the business hours across the entire Leon’s site to: Monday–Friday 8 AM–5 PM, Saturday by appointment. Check the header, footer, contact page, and schema/JSON-LD.

Add a new service page

Add a new service page to the Leon’s repo for “Outdoor Lighting Installation.” Use the existing service template. Wire it into the nav, footer, and homepage services grid. Update the sitemap.

Fix a typo across multiple pages

Search the Leon’s repo for the misspelling “recieve” and replace every instance with “receive.” Show me the diff before saving.

Update brand colors

Update the primary brand color on the Leon’s site from #DA8B30 to #C77A20. Show me everywhere it changes.

Run the visual diff against the source site

Run the pre-cutover visual diff workflow on Leon’s. Compare leons-landscaping.pages.dev against the live source at leonslandscapingllc.com. Use the 6-page sample.

(See the Pre-Cutover Visual Diff SOP for the full method.)

---

6. Cutover process (DNS flip)

When client approves their test URL, you flip DNS to make the production domain serve the new site. The most-care-required step in the entire pipeline. Done wrong, you can break their email, kill SEO rankings, or take their site offline.

The cutover sequence

sequenceDiagram
  participant Client
  participant You as Web Designer
  participant CF as Cloudflare<br/>Pages
  participant DNS as DNS Registrar
  participant GSC as Google<br/>Search Console

  Client->>You: Approves test URL in writing
  You->>You: Pre-cutover checklist<br/>(MX records, subdomains,<br/>URL parity, GSC access)
  You->>CF: Add production domain<br/>as Custom Domain
  CF-->>You: Required DNS records
  You->>DNS: Update A/CNAME → Cloudflare
  You->>DNS: Preserve MX, SPF, DKIM, DMARC
  Note over DNS: Wait 15-60 min<br/>for propagation
  You->>You: Test: site loads,<br/>email works,<br/>click 5+ min
  You->>CF: Remove noindex<br/>(via /site-cutover)
  You->>GSC: Re-verify property
  You->>GSC: Submit new sitemap
  Note over You: Monitor 72 hours

Silent vs. permissioned migration

Before scheduling the cutover, decide which type this is:

• Silent migration — Tekton already controls the domain registrar and DNS. We can flip without bothering the client (other than confirming the test URL looks good). Most Tekton-hosted clients fall here.
• Permissioned migration — client controls their registrar (GoDaddy, Squarespace, Network Solutions, etc.) and we need their cooperation. Most registrars require an OTP code emailed to the client to approve DNS changes. Plan for this — it’s the slowest part of cutover.

For permissioned migrations, get a 30-minute window confirmed with the client in writing before flipping anything. They need to be at their inbox to forward the OTP to you in real time.

Pre-cutover checklist

1. Document current DNS — pull the existing record set. Screenshot it. Backup.
2. Get email records — MX, SPF, DKIM, DMARC. Without these, client loses email.
3. Inventory subdomains — mail.client.com, webmail., shop., etc.
4. List third-party integrations — payment, booking, chat, analytics
5. Audit URL structure — every URL on source must exist on new site OR have a 301 redirect set up
6. Confirm GSC access — client verifies new property post-cutover
7. Confirm GA4 access — analytics tracking should keep working
8. Pick a low-traffic time — avoid Mondays, avoid right before email blasts
9. Get client written approval — email or signed handoff doc. “Looks good” in DM is not enough.
10. For permissioned migrations: confirm OTP forwarding — client needs to be available the moment you submit the DNS change so they can forward the OTP code back to you within ~10 minutes.

DNS propagation reality: the official SLA is 24-48 hours, but in practice most updates propagate within minutes. Don’t panic-roll-back at 15 minutes. Use https://dnschecker.org to see propagation status worldwide before assuming something’s broken.

The flip

1. Add production domain to CF Pages: dashboard → Pages → <client> → Custom domains → Add
2. Update DNS at registrar:
   • A record / CNAME → Cloudflare Pages
   • Preserve all MX records exactly (email-doesn’t-break step)
   • Preserve SPF, DKIM, DMARC TXT records
3. Wait for propagation (15–60 min, sometimes hours)
4. Test:
   • Production URL loads new site
   • Send test email to/from client domain
   • Click around the site for 5+ minutes
5. Remove noindex from production
6. Re-verify Google Search Console
7. Submit new sitemap to GSC

Post-cutover monitoring (72 hours)

• Check site daily
• Watch GSC for crawl errors
• Expect “where did rankings go” panic from client (answer: usually fine, give it a week)

Rollback plan

• Keep old DNS records on file
• If catastrophic, revert DNS to old site
• Tell Nick immediately

---

7. Pilot rollout plan

We start with 2 client cutovers to test before rolling out to all 18.

Pilot client criteria

Pick clients meeting all of these:

• Tekton-hosted (we control domain registration), not paying Squarespace/Wix directly
• Low-stakes — not about to launch a major campaign
• Available for client communication during cutover
• Clean source site (not 500+ blog posts)

Avoid: e-commerce carts, mid-campaign clients, complex GHL automations.

Nick picks the 2.

Pilot process

1. Pick client #1
2. Send test URL for review
3. Iterate on feedback (branch → test → merge)
4. Get written client approval
5. Run full pre-cutover checklist
6. Flip DNS
7. Monitor 72 hours
8. Document surprises in the Tekton wiki

Repeat for client #2.

If both go smooth → roll out to all. If anything breaks → stop, document, fix process, resume after Nick’s signoff.

---

8. Logging, audit trail, accountability

Every change to a client site is traceable: what changed, who changed it, when, why.

Sources of truth

• Per-commit log — git log (every commit, author, timestamp, message). Tell Claude “show me the last 10 commits on the leons repo” anytime.
• Per-PR log — GitHub Pull Requests page (title, description, author, files)
• Per-deploy log — Cloudflare Pages dashboard (timestamp + commit hash)
• Per-site log — ~/Projects/seo-ops-skills/logs/<client-slug>.md running journal

Required: per-site log

After every PR you merge, tell Claude:

Add a log entry to leons-landscaping.md saying I updated the phone number from (X) to (Y), referencing PR #12.

Claude appends the entry. One line per change.

Branch protection (Nick configures)

For every client repo:

• main is protected (no direct pushes)
• PRs require 1 approval + passing build check
• Cannot delete main

This is the audit trail backbone.

---

9. Troubleshooting

When things go sideways, you can usually just tell Claude what’s broken and ask it to investigate. But here are some common patterns:

Local dev server won’t start

The dev server won’t start. Check what’s wrong — try reinstalling node_modules and confirm Node version is 20+.

My change isn’t showing on the live site

I just merged PR #X but the change isn’t live yet. Check the Cloudflare Pages dashboard for build status, and check whether the commit actually pushed to origin/main.

If Cloudflare says deployed but you don’t see it in your browser → hard refresh (Cmd+Shift+R) to bypass cache.

Astro build failed in deploy

The Cloudflare deploy is failing. Pull the build log and figure out what’s wrong. Try running npm run build locally to reproduce.

Committed a file with secrets

• Tell Nick immediately, don’t push it. We’ll rotate the secret and rewrite git history before pushing.

DNS not propagating after cutover

• Use https://dnschecker.org to see propagation status worldwide
• Wait 30+ minutes before panicking
• Some ISPs cache DNS up to 24 hours

Forms aren’t submitting on the new site

• Original forms (Squarespace/GHL/WordPress) don’t work cross-domain. Each form needs to be replaced with a GoHighLevel embed during cutover. Tell Nick which forms you’re seeing, get the GHL location to route to, then prompt Claude to swap the form code.

---

10. When to escalate to Nick

Ping Nick (Slack / text):

• DNS work on first 2 cutovers (talk through before flipping)
• Anything touching the live site you’re unsure about
• Client wants something needing redesign / new template
• Build failing and you can’t figure out why
• Client unhappy with migration
• Something weird on live site you didn’t change

Don’t ping Nick for:

• “How do I edit copy?” — section 5 above (just prompt Claude)
• “How do I make a branch?” — section 4 above (just prompt Claude)
• “Pages.dev URL for client X?” — Cloudflare dashboard or clients.json

---

Definition of done

You’re onboarded when:

• GitHub account created with 2FA, accepted Tektongrowth org invite
• Claude Code desktop app installed and logged in
• Homebrew, Node, Git, GitHub CLI installed (one-time terminal setup)
• gh auth login completed
• Cloudflare invite accepted, 2FA on
• Successfully cloned a client repo via Claude Code, ran the dev server, viewed the site at localhost in your browser
• Created a test branch, made a trivial change, pushed, opened a PR, merged via GitHub UI — all by prompting Claude
• Read sections 4 and 6 in full and can explain the workflow back to Nick

---

Quick reference card

Things to say to Claude Code desktop, by task:

Task	What to tell Claude
Start fresh on a repo	”Pull latest main on the leons repo.”
New branch	”Create a branch called fix/leons-hours and switch to it.”
Make an edit	”On the contact page, update the phone to (513) 555-1234. Show me the diff.”
Test locally	”Start the local dev server.” (then open localhost in your browser to check)
Stop server	”Stop the dev server.”
Commit + push branch	”Commit these changes with message ‘fix: phone number’ and push the branch.”
Open PR	”Open a Pull Request on GitHub for this branch. Describe what changed.”
Verify deploy	”Show me the latest deployment status for leons on Cloudflare Pages.”
Roll back	”Revert the last commit on main and push immediately.”
Log the change	”Add an entry to the leons site log: updated phone number, PR #X.”

If you forget any of these, just describe what you want in plain English. Claude figures it out.

---

Version Control

• v1.2 (2026-04-30): Replaced manual brew installs with one-command toolkit install (tekton-toolkit-web-designer repo).
• v1.1 (2026-04-30): Switched workflow to Claude Code desktop app instead of CLI/terminal.
• v1.0 (2026-04-30): Initial SOP with terminal-driven workflow.