Full Stack Workspace Init

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

# Create workspace with PRD-style prompt
python3 ~/.claude/skills/fullstack-workspace-init/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 ~/.claude/skills/fullstack-workspace-init/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
├── .agent/                     # AI documentation
├── package.json                # Workspace root
├── biome.json                  # Root lintin

...