fullstack-workspace-init

What this skill does

# Full Stack Workspace Init

Create a Shipshit.dev product workspace. For new product repos, use
`npx @shipshitdev/v0` as the default scaffolder and treat this skill as the
product-brief, customization, and verification layer.

## Contract

Inputs:

- Project directory and product name
- Product scope or PRD-style brief
- Selected app surfaces and product routes
- Agent handoff preference: codex, claude, or skip-agent

Outputs:

- v0 command or interactive route used
- Generated workspace summary
- Quality gate and startup status
- Follow-up tasks for app-specific customization

Creates/Modifies:

- New Bun/Turbo product repo when v0 runs
- `.agents/skills`, `.agents/memory`, `.claude`, `.codex`, apps, packages, and `.v0` files generated by v0
- App-specific files only when customizing after v0 generation

External Side Effects:

- May install dependencies and start `apps/web`
- May create GitHub repo/issues only when GitHub flags are explicitly enabled

Confirmation Required:

- Before creating a GitHub repo or issue
- Before running in a non-empty directory
- Before overwriting generated app files after v0 completes

Delegates To:

- `project-init-orchestrator` for route selection
- `agent-folder-init` only for existing repos not generated by v0
- `testing-cicd-init`, `linter-formatter-init`, and `shadcn-setup` for repair/customization
- `scaffold` for incremental modules inside the generated workspace

## Default v0 Route

For new Shipshit.dev product repos, run:

```bash
npx @shipshitdev/v0 <project-directory>
```

Use non-interactive mode when the user gives enough detail:

```bash
npx @shipshitdev/v0 <project-directory> \
  --scope "<product scope>" \
  --agent codex \
  --apps web,app,desktop,mobile,extension,cli \
  --routes overview,new-task,search,inbox,activities \
  --no-github
```

Use `--skip-agent`, `--no-install`, and `--no-start` for CI/smoke tests or when
the user only wants the scaffold written.

## Legacy Manual Route

Use the manual guidance below only when v0 is not appropriate or when enhancing
an existing workspace that already has its core scaffold.

Do not use this route for a new Shipshit.dev product repo unless v0 is
unavailable or the user explicitly asks to bypass it.

Create a **production-ready** monorepo with working MVP features:

- **Frontend:** NextJS 16 + React 19 + TypeScript + Tailwind + @agenticindiedev/ui
- **Backend:** NestJS 11 + MongoDB + Clerk Auth + Swagger
- **Mobile:** React Native + Expo (optional)
- **Quality:** Vitest (80% coverage) + Biome + Husky + GitHub Actions CI/CD
- **Package Manager:** bun

## What Makes This Different

This skill generates **working applications**, not empty scaffolds:

- Complete CRUD operations for your main entities
- Clerk authentication configured and working
- Tests with 80% coverage threshold
- GitHub Actions CI/CD pipeline
- Runs immediately with `bun dev`

---

## Workflow

### Phase 1: PRD Brief Intake

**Ask the user for a 1-2 paragraph product description**, then extract and confirm:

```
I'll help you build [Project Name]. Based on your description, I understand:

**Entities:**
- [Entity1]: [fields]
- [Entity2]: [fields]

**Features:**
- [Feature 1]
- [Feature 2]

**Routes:**
- / - Home/Dashboard
- /[entity] - List view
- /[entity]/[id] - Detail view

**API Endpoints:**
- GET/POST /api/[entity]
- GET/PATCH/DELETE /api/[entity]/:id

Is this correct? Any adjustments?
```

### Phase 2: Auth Setup (Always Included)

Generate Clerk authentication:

**Backend:**

- `auth/guards/clerk-auth.guard.ts` - Token verification guard
- `auth/decorators/current-user.decorator.ts` - User extraction decorator

**Frontend:**

- `providers/clerk-provider.tsx` - ClerkProvider wrapper
- `app/sign-in/[[...sign-in]]/page.tsx` - Sign in page
- `app/sign-up/[[...sign-up]]/page.tsx` - Sign up page
- `middleware.ts` - Protected route middleware

**Environment:**

- `.env.example` with all required variables

### Phase 3: Entity Generation

For each extracted entity, generate complete CRUD **with tests**:

**Backend (NestJS):**

```
api/apps/api/src/collections/{entity}/
├── {entity}.module.ts
├── {entity}.controller.ts         # Full CRUD + Swagger + ClerkAuthGuard
├── {entity}.controller.spec.ts    # Controller unit tests
├── {entity}.service.ts            # Business logic
├── {entity}.service.spec.ts       # Service unit tests
├── schemas/
│   └── {entity}.schema.ts         # Mongoose schema with userId
└── dto/
    ├── create-{entity}.dto.ts     # class-validator decorators
    └── update-{entity}.dto.ts     # PartialType of create

api/apps/api/test/
├── {entity}.e2e-spec.ts           # E2E tests with supertest
└── setup.ts                       # Test setup with MongoDB Memory Server
```

**Frontend (NextJS):**

```
frontend/apps/dashboard/
├── app/{entity}/
│   ├── page.tsx                   # List view (protected)
│   └── [id]/page.tsx              # Detail view (protected)
├── src/test/
│   └── setup.ts                   # Test setup with Clerk mocks
└── vitest.config.ts               # Frontend test config (jsdom)

frontend/packages/components/
├── {entity}-list.tsx
├── {entity}-list.spec.tsx         # Component tests
├── {entity}-form.tsx
├── {entity}-form.spec.tsx         # Component tests
└── {entity}-item.tsx

frontend/packages/hooks/
├── use-{entities}.ts              # React hook for state management
└── use-{entities}.spec.ts         # Hook tests

frontend/packages/services/
└── {entity}.service.ts            # API client with auth headers
```

### Phase 4: Quality Setup

**Vitest Configuration:**

- `vitest.config.ts` in each project
- 80% coverage threshold for lines, functions, branches
- `@vitest/coverage-v8` provider

**GitHub Actions:**

- `.github/workflows/ci.yml`
- Runs on push to main and PRs
- Steps: install → lint → test → build

**Husky Hooks:**

- Pre-commit: `lint-staged` (Biome check)
- Pre-push: `bun run typecheck`

**Biome:**

- `biome.json` in each project
- 100 character line width
- Double quotes, semicolons

### Phase 5: Verification

Run quality gate and report results:

```
✅ Generation complete!

Quality Report:
- bun install: ✓ succeeded
- bun run lint: ✓ 0 errors
- bun run test: ✓ 24 tests passed
- Coverage: 82% (threshold: 80%)

Ready to run:
  cd [project]
  bun dev
```

---

## Usage

```bash
# Create workspace with PRD-style prompt
python3 scripts/init-workspace.py \
  --root ~/www/myproject \
  --name "My Project" \
  --brief "A task management app where users can create tasks with titles and due dates, organize them into projects, and mark them complete."

# Or interactive mode (prompts for brief)
python3 scripts/init-workspace.py \
  --root ~/www/myproject \
  --name "My Project" \
  --interactive
```

---

## Generated Structure

```
myproject/
├── .github/
│   └── workflows/
│       └── ci.yml              # GitHub Actions CI/CD
├── .husky/
│   ├── pre-commit              # Lint staged files
│   └── pre-push                # Type check
├── .agents/                     # AI documentation
├── package.json                # Workspace root
├── biome.json                  # Root linting config
│
├── api/                        # NestJS backend
│   ├── apps/api/src/
│   │   ├── main.ts
│   │   ├── app.module.ts
│   │   ├── auth/
│   │   │   ├── guards/clerk-auth.guard.ts
│   │   │   ├── guards/clerk-auth.guard.spec.ts  # Auth guard tests
│   │   │   └── decorators/current-user.decorator.ts
│   │   └── collections/
│   │       └── {entity}/
│   │           ├── {entity}.controller.ts
│   │           ├── {entity}.controller.spec.ts  # Controller tests
│   │           ├── {entity}.service.ts
│   │           └── {entity}.service.spec.ts     # Service tests
│   ├── apps/api/test/
│   │   ├── {entity}.e2e-spec.ts                 # E2E tests
│   │   └── setup.ts                             # E2E test setup
│   ├── vitest.config.ts
│   ├── package.json
│   └── .env.example
│
├── frontend/                   # NextJS apps
│   ├── apps/dashboard/
│   │