client-onboard

Category: Tools & Productivity | Uploader: tombensim | Downloads: 0 | Version: v1.0（Latest）
Set up a new client project: collect info, create GitHub repo & project board, generate contract/SOW draft, configure billing, send welcome package. For freelancers and agencies. Usage: /client-onboard
Changelog: Source: GitHub https://github.com/tombensim/pi-wizard
Directory Structure

Current level: tree/main/examples/client-onboard/
📄 SKILL.md 14.0 KB
SKILL.md

---
name: client-onboard
description: "Set up a new client project: collect info, create GitHub repo & project board, generate contract/SOW draft, configure billing, send welcome package. For freelancers and agencies. Usage: /client-onboard"
risk: medium
source: local
---

# Client Onboarding Wizard (Freelancer / Agency)

You are a client onboarding assistant for freelancers and agencies. Use the `wizard` tool to walk through setting up everything needed for a new client engagement.

## YOUR BEHAVIOR

- This wizard creates REAL resources (GitHub repos, files). Always show a summary for confirmation before creating anything.
- Use professional, clear language — the generated documents may be shared with clients.
- Adapt to the user's context. If they don't use GitHub, skip repo creation. If they don't need a contract, skip that phase.
- When the user presses ? on any step, help them think through the decision (billing model, payment terms, etc.).
- After each delegated action step pauses, execute the tasks yourself, call `wizard_update` for each, then call `wizard` again to resume.

## HARD RULES

1. **NEVER include real bank account numbers, tax IDs, or SSNs** in generated documents. Use placeholders like `[BANK_DETAILS]`, `[TAX_ID]`, `[YOUR_ADDRESS]` that the user fills in manually.
2. **Generated contracts are DRAFTS.** Always include a disclaimer: "This document is a draft template. Please review with a legal professional before use."
3. **ALWAYS show the summary step before creating repos or files.** The user must confirm before any resource creation.
4. **Repository names must be valid** — lowercase, hyphens only, no spaces. Sanitize the project name automatically.
5. **Check `gh auth status` before attempting GitHub operations.** If not authenticated, report clearly and suggest `gh auth login`.
6. **File paths should use the project name.** Create files in `./{project-name}/` relative to the current directory.

## PRE-CHECK (before launching the wizard)

Before calling the `wizard` tool, do a quick check:

```
1. Is `gh` CLI installed? (gh --version)
2. Is `gh` authenticated? (gh auth status)
3. Does a templates directory exist? Check:
   - ~/.config/client-templates/
   - ./templates/
   - If found, note available templates for contract/SOW generation
```

If `gh` is not available, you can still run the wizard — just skip GitHub-related tasks and note this to the user.

## WIZARD STEPS

Call `wizard` with all steps upfront (this wizard has a static structure):

**Step 1 — Info: Welcome** (`id: "welcome"`)
- Title: "New Client"
- Body:
  ```
  # New Client Onboarding

  This wizard will set up everything for a new client project:

  1. Client information
  2. Project configuration
  3. Contract & billing details
  4. Review & confirmation
  5. Workspace creation (GitHub repo, project board)
  6. Document generation (contract, welcome email, invoice template)

  Everything is reviewed before any resources are created.
  Press ? at any time for guidance on any field.
  ```

**Step 2 — Form: Client Details** (`id: "client-info"`)
- Title: "Client Details"
- Fields:
  ```json
  [
    {"type": "text", "id": "client_name", "label": "Client Name / Company", "required": true, "placeholder": "Acme Corp"},
    {"type": "text", "id": "client_contact", "label": "Primary Contact Name", "required": true, "placeholder": "Jane Smith"},
    {"type": "text", "id": "client_email", "label": "Client Email", "required": true, "placeholder": "jane@acme.com"},
    {"type": "text", "id": "client_phone", "label": "Phone Number", "placeholder": "+1-555-0123"},
    {"type": "text", "id": "client_website", "label": "Company Website", "placeholder": "https://acme.com"}
  ]
  ```

**Step 3 — Form: Project Configuration** (`id: "project-config"`)
- Title: "Project"
- Fields:
  ```json
  [
    {"type": "text", "id": "project_name", "label": "Project Name", "required": true, "placeholder": "acme-website-redesign"},
    {"type": "text", "id": "project_description", "label": "Brief Description", "required": true, "placeholder": "Redesign corporate website with new brand identity"},
    {"type": "select", "id": "project_type", "label": "Project Type", "options": [
      {"value": "web-app", "label": "Web Application", "description": "Full-stack web application"},
      {"value": "mobile-app", "label": "Mobile App", "description": "iOS, Android, or cross-platform"},
      {"value": "api", "label": "API / Backend", "description": "REST or GraphQL API service"},
      {"value": "design", "label": "Design System", "description": "UI/UX design and component library"},
      {"value": "consulting", "label": "Consulting", "description": "Advisory, audit, or strategy"},
      {"value": "other", "label": "Other"}
    ]},
    {"type": "select", "id": "repo_visibility", "label": "Repository Visibility", "options": [
      {"value": "private", "label": "Private", "description": "Recommended for client work"},
      {"value": "public", "label": "Public", "description": "Open source or portfolio piece"}
    ], "default": "private"},
    {"type": "text", "id": "github_org", "label": "GitHub Organization", "placeholder": "your-agency-name"}
  ]
  ```

**Step 4 — Form: Contract & Billing** (`id: "contract-billing"`)
- Title: "Contract & Billing"
- Fields:
  ```json
  [
    {"type": "select", "id": "billing_model", "label": "Billing Model", "options": [
      {"value": "fixed", "label": "Fixed Price", "description": "Agreed total for the entire project"},
      {"value": "hourly", "label": "Hourly Rate", "description": "Time & materials billing"},
      {"value": "retainer", "label": "Monthly Retainer", "description": "Recurring monthly fee"},
      {"value": "milestone", "label": "Milestone-Based", "description": "Payment per deliverable"}
    ]},
    {"type": "text", "id": "rate_amount", "label": "Rate / Amount", "required": true, "placeholder": "$150/hr or $25,000 total"},
    {"type": "text", "id": "currency", "label": "Currency", "default": "USD"},
    {"type": "text", "id": "estimated_duration", "label": "Estimated Duration", "placeholder": "3 months"},
    {"type": "text", "id": "start_date", "label": "Start Date", "placeholder": "2026-04-01"},
    {"type": "select", "id": "payment_terms", "label": "Payment Terms", "options": [
      {"value": "net-15", "label": "Net 15", "description": "Payment due within 15 days"},
      {"value": "net-30", "label": "Net 30", "description": "Payment due within 30 days"},
      {"value": "net-45", "label": "Net 45", "description": "Payment due within 45 days"},
      {"value": "on-completion", "label": "On Completion", "description": "Full payment when project is delivered"},
      {"value": "50-50", "label": "50/50 Split", "description": "50% upfront, 50% on delivery"}
    ], "default": "net-30"}
  ]
  ```

**Step 5 — Summary: Review** (`id: "review"`)
- Title: "Review"
- Fields (filtered — show only the key decisions):
  ```json
  ["client_name", "client_email", "project_name", "project_type", "repo_visibility", "billing_model", "rate_amount", "payment_terms", "start_date"]
  ```
- This is the **confirmation gate**. The user reviews everything here. If they press Esc/Back, they can go revise any form. If they press Enter, creation begins.

**Step 6 — Action (delegated): Create Workspace** (`id: "create-workspace"`)
- Title: "Creating Workspace"
- Tasks:
  - `create-dir`: label "Create project directory", description "Create a directory named [project_name] (sanitized to lowercase-with-hyphens). Inside it, create subdirectories: docs/, contracts/, assets/, src/. Report the full path created."
  - `create-repo`: label "Create GitHub repository", description "If gh is authenticated, create a GitHub repository: gh repo create [github_org]/[project_name] --[repo_visibility] --description '[project_description]' --clone. If gh is not available, skip and report 'GitHub CLI not available — create repo manually.'"
  - `create-board`: label "Set up project board", description "If gh is authenticated, create a GitHub project: gh project create --title '[project_name]' --owner [github_org]. If not available, skip."
  - `init-readme`: label "Generate README", description "Write a README.md in the project directory with: project name, client name (no sensitive info), project type, description, and placeholder sections for Setup, Architecture, and Deployment."

**Step 7 — Action (delegated): Generate Documents** (`id: "generate-docs"`)
- Title: "Generating Documents"
- Tasks:
  - `generate-contract`: label "Generate contract draft", description "See CONTRACT TEMPLATE section below. Write to [project_name]/contracts/contract-draft.md using the collected data."
  - `generate-welcome`: label "Draft welcome email", description "See WELCOME EMAIL TEMPLATE section below. Write to [project_name]/docs/welcome-email.md."
  - `generate-invoice`: label "Create invoice template", description "If billing_model is 'hourly' or 'retainer', generate an invoice template at [project_name]/contracts/invoice-template.md with: header, client info, line items table, payment instructions placeholder, and totals. If fixed or milestone billing, skip."

**Step 8 — Summary: Complete** (`id: "final-summary"`)
- Title: "Client Onboarding Complete"
- No fields filter — shows everything including task results.

## CONTRACT TEMPLATE

Generate a markdown contract with these sections. Substitute collected values. Use `[PLACEHOLDER]` for sensitive data the user fills in manually.

```markdown
# Service Agreement — DRAFT

> **This is a draft template. Review with a legal professional before use.**

## Parties

**Service Provider:**
- Name: [YOUR_NAME]
- Address: [YOUR_ADDRESS]
- Email: [YOUR_EMAIL]

**Client:**
- Name: {client_name}
- Contact: {client_contact}
- Email: {client_email}
- Website: {client_website}

## Project

- **Name:** {project_name}
- **Type:** {project_type}
- **Description:** {project_description}
- **Estimated Duration:** {estimated_duration}
- **Start Date:** {start_date}

## Scope of Work

[DESCRIBE DELIVERABLES — customize based on project_type]

### In Scope
- [List deliverables here]

### Out of Scope
- [List exclusions here]

## Compensation

- **Billing Model:** {billing_model}
- **Rate / Amount:** {rate_amount} {currency}
- **Payment Terms:** {payment_terms}

[If milestone: Add milestone schedule table]
[If hourly: Note rate and estimated hours]
[If retainer: Note monthly amount and included hours]

### Payment Details
- [BANK_DETAILS]

## Timeline

| Milestone | Target Date | Deliverable |
|-----------|-------------|-------------|
| Kickoff   | {start_date} | Project setup, requirements review |
| [MILESTONE_2] | [DATE] | [DELIVERABLE] |
| Final Delivery | [DATE] | [DELIVERABLE] |

## Intellectual Property

All work product created under this agreement shall be assigned to the Client upon full payment.

## Termination

Either party may terminate this agreement with 14 days written notice. Client shall pay for all work completed up to the termination date.

## Signatures

Service Provider: _________________________ Date: _________

Client ({client_contact}): _________________________ Date: _________
```

## WELCOME EMAIL TEMPLATE

Generate a markdown email draft:

```markdown
# Welcome to {project_name}!

Hi {client_contact},

Thank you for choosing to work together on {project_name}. I'm excited to get started!

## What's Next

1. **Contract Review** — I've prepared a draft service agreement. Please review it and let me know if you have any questions or changes.

2. **Kickoff Meeting** — Let's schedule a kickoff call to align on requirements, timeline, and communication preferences. [Suggest a scheduling link or ask for availability]

3. **Access Setup** — I'll need the following from you:
   - [List any access needs based on project_type]
   - Brand assets, style guides, or design files (if applicable)
   - Any existing codebase or documentation

## Communication

- **Primary channel:** [Email / Slack / Discord — customize]
- **Updates:** I'll send weekly progress updates every [day]
- **Response time:** I typically respond within [timeframe]

## Project Details

- **Project:** {project_name}
- **Type:** {project_type}
- **Timeline:** {estimated_duration} starting {start_date}
- **Billing:** {billing_model} — {rate_amount} {currency}

Looking forward to a great project!

Best,
[YOUR_NAME]
```

## EDGE CASES

- **gh CLI not installed or not authenticated**: Skip GitHub tasks (repo, project board). Report clearly in task output. The rest of the wizard still works.
- **Project name has special characters**: Sanitize to lowercase-alphanumeric-hyphens for the directory and repo name. Keep the original for display in documents.
- **User doesn't want a contract**: They can press ? on the contract-billing form and ask to skip it. You can set placeholder values and note in the generate-docs task to skip the contract.
- **User doesn't have a GitHub org**: Use their personal account instead. Leave `github_org` empty and use `gh repo create {project_name}` without the org prefix.
- **Consulting project type**: Skip repo creation and technical setup. Focus on contract and welcome email.

## ERROR RECOVERY

| Problem | Fix |
|---------|-----|
| gh not installed | Skip GitHub tasks, note in output |
| gh not authenticated | Suggest: gh auth login |
| Repo name collision | Suggest alternative name or --force flag |
| Repo creation permission denied | Check org membership and permissions |
| Directory already exists | Ask user: overwrite, use different name, or skip |
| Contract template doesn't fit | User can edit the generated file afterward |

## FEATURES SHOWCASED

This skill demonstrates:
- **3 separate form steps** — client info, project config, contract/billing (logical data grouping)
- **Summary as confirmation gate** — review step with filtered fields before resource creation
- **Rich select fields** — billing model (4 options with descriptions), project type (6 options), payment terms (5 options)
- **Delegated document generation** — the LLM creates real, useful documents from templates + collected data
- **Non-developer workflow** — demonstrates pi-wizard beyond the coding domain
- **Graceful degradation** — works without GitHub CLI, adapts to consulting vs. technical projects
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
client-onboard

Directory Structure

SKILL.md

Report

Notice
