Meta New Client Project

New Client Project — Full Onboarding Pipeline

Overview

Automates the full pipeline from signed SOW to a tracked, documented, repo-backed project folder. Handles GitHub repo creation under Persimmon-Automation-Labs, local clone, doc scaffolding (via meta-document-project), initial commit, and registration in the Persimmon clients index.

This skill handles setup only. Architecture decisions, MVP scoping, and stack scaffolding (Next.js 16 skeleton, Prisma, auth, etc.) happen via separate skills — nextjs-project-scaffolding, data-prisma-pgvector, security-nextauth, etc.

Step 0: Collect Required Inputs Up-Front

Before running anything, gather ALL of these. If any are missing, ask the user — don't guess.

Slug rules: lowercase, hyphenated, short. "Almeida Prado e Piccino Advogados" → piccino-legal. "Garrido USA Industries" → garrido. Ask to confirm the slug before creating the repo — the name is hard to change later.

Step 1: Preflight Checks

Run all checks in parallel. Stop on any failure and tell the user how to fix.

1a. gh CLI installed

gh --version

If missing:

gh CLI not installed. Install with brew install gh (Mac) or winget install GitHub.cli (Windows), then gh auth login.

1b. Authenticated as renatodap

gh auth status 2>&1

Persimmon projects require the renatodap account (org admin for Persimmon-Automation-Labs). If the output shows a different active user:

gh auth switch --user renatodap

Re-run gh auth status to confirm.

1c. Persimmon-Automation-Labs org access

gh api orgs/Persimmon-Automation-Labs --jq '.login'

Must return Persimmon-Automation-Labs. If 404, the user is not a member of the org — stop and tell them.

1d. git installed

git --version

1e. Locate Persimmon parent directory

Persimmon client repos live under ~/Documents/Projects/ (or equivalent — the active {PROJECTS} base). No parent monorepo — each client is standalone.

# Mac default
PROJECTS_ROOT="$HOME/Documents/Projects"
ls "$PROJECTS_ROOT" >/dev/null 2>&1 || { echo "ERR: Projects dir missing"; exit 1; }

1f. Source skills repo is available

SKILLS_REPO="$HOME/Documents/Projects/persimmon-claude-skills"
ls "$SKILLS_REPO/skills/meta-document-project/SKILL.md" >/dev/null 2>&1

If missing, the user should clone persimmon-claude-skills first — we need it for Step 5.

Step 2: Check for Existing Repo / Folder

2a. Does the repo already exist on GitHub?

gh repo view "Persimmon-Automation-Labs/$SLUG" --json name,url 2>/dev/null

If it exists:

Repo Persimmon-Automation-Labs/$SLUG already exists at {url}. Want to clone it locally and scaffold docs, or pick a different slug?

2b. Does a local folder already exist?

ls -la "$PROJECTS_ROOT/$SLUG/.git" 2>/dev/null

Step 3: Create GitHub Repo

gh repo create "Persimmon-Automation-Labs/$SLUG" \
  --private \
  --description "$CLIENT_NAME — $DOMAIN" \
  --clone=false \
  --add-readme=false

Do not add a README via gh — meta-document-project generates a better one.

Verify:

gh repo view "Persimmon-Automation-Labs/$SLUG" --json url

Step 4: Clone Locally

cd "$PROJECTS_ROOT"
git clone "https://github.com/Persimmon-Automation-Labs/$SLUG.git"
cd "$SLUG"

# Create skeleton directories
mkdir -p docs/{decisions,reference} notes src .github/workflows

# Set up .claude/ skills via skill-sync skill (Mode A)
git clone https://github.com/Persimmon-Automation-Labs/persimmon-claude-skills.git .claude
echo ".claude/" >> .gitignore

Do this cleanly — no stray files yet.

Step 5: Scaffold Documentation

Delegate to the meta-document-project skill in SCAFFOLD mode. Pass the collected inputs:

• client_name — $CLIENT_NAME
• domain — $DOMAIN
• summary — $PROJECT_SUMMARY
• contact — $CONTACT_NAME, $CONTACT_EMAIL, $CONTACT_TITLE
• deliverables — parsed bullet list
• timeline — $TIMELINE
• proposal_number — $PROPOSAL_NUMBER
• stack_deltas — $STACK_DELTAS (if any)

meta-document-project creates:

• CLAUDE.md (dev context, Persimmon stack conventions)
• README.md (status, team, setup, doc links — ≤ 80 lines)
• docs/reference/scope-of-work.md (financials, deliverables — only place for $)
• .github/workflows/ci.yml (lint, typecheck, prisma validate, build)

Review generated files before committing — make sure client name, contact, and deliverables are accurate.

Step 6: Register in Persimmon Clients Index

Persimmon maintains a clients.json index at the root of persimmon-claude-skills. Add this project.

Check for the index:

INDEX="$SKILLS_REPO/clients.json"
if [ ! -f "$INDEX" ]; then
  echo '{"clients": []}' > "$INDEX"
fi

Append the new client (use jq for safe JSON edit):

jq --arg slug "$SLUG" \
   --arg name "$CLIENT_NAME" \
   --arg domain "$DOMAIN" \
   --arg repo "https://github.com/Persimmon-Automation-Labs/$SLUG" \
   --arg started "$(date +%Y-%m-%d)" \
   '.clients += [{
      slug: $slug,
      name: $name,
      domain: $domain,
      repo: $repo,
      started: $started,
      status: "active"
    }]' "$INDEX" > "$INDEX.tmp" && mv "$INDEX.tmp" "$INDEX"

Also update the Client Projects table in persimmon-claude-skills/CLAUDE.md:

| {Client Name} | {Domain} | `{slug}` (private) | {URL or TBD} |

Commit these changes in the skills repo:

cd "$SKILLS_REPO"
git add clients.json CLAUDE.md
git commit -m "Register $SLUG — $CLIENT_NAME"
git push

Step 7: Initial Commit and Push

cd "$PROJECTS_ROOT/$SLUG"
git add -A
git commit -m "Initial scaffold: docs, CI, lean structure

- CLAUDE.md (Persimmon stack context)
- README.md (status, team, setup)
- docs/reference/scope-of-work.md
- docs/decisions/ (ready for ADRs)
- .github/workflows/ci.yml
- .claude/ skills (gitignored)
"
git branch -M main
git push -u origin main

Verify CI runs green — watch the Actions tab. If it fails, it's almost always because a prisma schema or pnpm install step was expected but scaffolding only covered docs. That's fine at this stage; the next skill (nextjs-project-scaffolding) will flesh out the project.

Step 8: Summary

NEW CLIENT PROJECT — {Client Name}
============================================
Slug:       {slug}
GitHub:     https://github.com/Persimmon-Automation-Labs/{slug}
Local:      {PROJECTS_ROOT}/{slug}/
Status:     Registered in Persimmon clients index

FILES CREATED:
  CLAUDE.md                          — Dev context (Persimmon stack)
  README.md                          — Human onboarding
  docs/reference/scope-of-work.md    — Contract + financials
  docs/decisions/                    — Ready for ADRs
  docs/reference/                    — Ready for client materials
  notes/                             — Ready for meeting notes
  .github/workflows/ci.yml           — Lint/typecheck/build
  .claude/                           — Persimmon skills (gitignored)

NEXT STEPS:
  1. Review generated docs for accuracy (client name, contact, deliverables)
  2. Run `nextjs-project-scaffolding` to lay down the Next.js 16 skeleton
  3. Run `data-prisma-pgvector` for schema + pgvector + HNSW
  4. Run `security-nextauth` for auth
  5. Run `infra-railway-deploy` to provision the Railway project
============================================

Error Recovery

What This Skill Does NOT Do

• Architecture decisions — separate conversation, captured later via meta-adr-authoring
• MVP scoping — that's a product conversation, not automation
• Next.js / Prisma / auth / Claude SDK scaffolding — separate skills in the pipeline
• Railway project creation — infra-railway-deploy skill
• Domain purchase / DNS — manual
• Client onboarding call / kickoff — manual