project-init-orchestrator

Project Init Orchestrator

Choose the smallest safe setup route. For new Shipshit.dev product repos, prefer npx @shipshitdev/v0 as the primary scaffolder, then customize and verify the generated workspace. Use the lower-level init skills for existing repos, repairs, or project types not covered by v0.

Authorized Scope

Act only within the user's request and existing approval; loading this skill grants no new authority. Keep report-only requests report-only, honor the caller's target, host, provider, and cost limits, ask before expanding scope, and forward these limits to delegates.

Contract

Inputs:

• Target project path and project name
• Project type: new Shipshit.dev product, existing repo, docs-only, library, or custom
• Project directory and product name; product scope or PRD-style brief
• Desired app surfaces, routes, agent handoff (codex, claude, or skip-agent), and GitHub setup

Outputs:

• Selected initialization route
• List of delegated skills or v0 command used (the v0 command or interactive route)
• Generated workspace summary; files/directories created or modified
• Quality gate and startup status
• Follow-up tasks for app-specific customization and remaining manual setup

Creates/Modifies:

• New product repos through npx @shipshitdev/v0: a Bun/Turbo repo with .agents/skills, .agents/memory, .claude, .codex, apps, packages, and .v0 files generated by v0
• App-specific files only when customizing after v0 generation
• Existing repo .agents/, .claude/, .codex/, lint, test, and scaffold files when delegated

External Side Effects:

• May install dependencies and start apps/web when using v0 or delegated setup skills
• May create a GitHub repo or issue only when the v0 command is run with GitHub flags

Confirmation Required:

• Before creating a GitHub repo or issue
• Before running setup outside the current workspace, or in a non-empty directory
• Before overwriting existing agent/config files, or generated app files after v0 completes

Delegates To:

• agent-folder-init for existing repos that only need AI project context (not for repos generated by v0)
• linter-formatter-init, testing-cicd-init, husky-test-coverage, and shadcn (setup mode) for repo repair or post-v0 customization
• scaffold for small module/component additions inside an existing codebase

When to Use

This skill activates automatically when users:

• Start a new project from scratch
• Want full Shipshit.dev product setup with one command
• Need AI-first development infrastructure + code quality tools
• Say "initialize project", "set up new project", "bootstrap project"
• Want consistent setup across multiple projects

Skills Orchestrated

Order	Skill	Purpose	Required
1	npx @shipshitdev/v0	New Shipshit.dev product repo	Conditional
2	agent-folder-init	AI documentation & standards for existing repos	Conditional
3	linter-formatter-init	ESLint/Biome + formatter + pre-commit repair	Conditional
4	testing-cicd-init / husky-test-coverage	Test and CI gates	Optional
5	scaffold	Incremental module/component additions	Optional

Route Selection

Use this order:

1. New Shipshit.dev product repo: run npx @shipshitdev/v0.
2. New non-product repo: scaffold only the requested repo structure, then add agent docs and gates.
3. Existing repo missing AI context: run agent-folder-init.
4. Existing repo with weak quality gates: run linter/test/CI skills only.
5. Existing repo needing one feature/module: run scaffold after finding 3+ examples.

For v0-backed setup, use interactive mode unless the user provides all inputs:

npx @shipshitdev/v0 <project-directory>

For non-interactive Shipshit.dev product setup:

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 only when v0 is not appropriate or when enhancing an existing workspace. Do not use for new Shipshit.dev product repos unless v0 is unavailable or the user explicitly bypasses it.

Stack: Next.js 16 (proxy.ts) + React 19 + TypeScript 6 + Tailwind v4 CSS-first (frontend), NestJS 12 + Prisma 7/Postgres + Better Auth + Swagger (backend), Vitest 80% coverage + Biome + GitHub Actions CI, Bun package manager. Every dependency pin lives in the V table at the top of scripts/init-workspace.py; refresh it with npm view <pkg> version (Expo packages follow the SDK's bundledNativeModules.json, not the newest release).

Load references/legacy-manual-route.md for the full step-by-step workflow, generated structure, key code patterns, and development commands. Helper scripts live in scripts/ (init-workspace.py, add-api-collection.py, add-frontend-app.py). After generating, run bun install, copy .env.example to api/.env, run bun run prisma:migrate from api/, run bun run prisma:generate (Prisma 7 migrate no longer builds the client; repeat after every schema change), and run bun run lint:fix once so Biome formats the generated files. Collections added with add-api-collection.py are guarded by AuthGuard and scoped to the signed-in user from the session, never from request input.

Usage

Quick Start (Recommended)

When user says "initialize my project" or "set up new project":

1. Ask for project context:
   - Project path (default: current directory)
   - New Shipshit.dev product or existing repo repair?
   - Product scope if using v0
   - App surfaces and routes if non-default
   - Agent to hand off to: codex or claude
   - Need existing-repo repair or incremental scaffolding?

2. Execute phases in order:
   v0 route OR existing-repo phases → verification

Existing-Repo Repair

Use lower-level skills only after deciding v0 is not the right route:

1. agent-folder-init for AI docs and agent config.
2. linter-formatter-init for lint/format drift.
3. testing-cicd-init or husky-test-coverage for test and CI gates.
4. scaffold for a requested module, endpoint, component, or package.

Route Matrix

Request	Primary Route	Notes
New Shipshit.dev product repo	npx @shipshitdev/v0	Default route. Includes app surfaces and agent setup.
New non-product repo	Minimal scaffold + agent-folder-init	Keep setup proportional to the requested repo.
Existing repo AI context	agent-folder-init	No application source generation.
Existing repo quality gates	Linter/test/CI skills	Repair only the missing gates.
Existing repo feature/module	scaffold	Find 3+ local examples first.

Best Practices

Sequencing

• For new Shipshit.dev products, run v0 first.
• For existing repos, add AI docs before repo-specific repair work.
• Run linter and formatter setup before test hooks when both are missing.
• Run scaffold only after the target codebase patterns are known.

Customization

• Each phase can be skipped if already configured
• Phases are idempotent (safe to re-run)
• Configuration can be customized after orchestration

Verification Checklist

After orchestration, verify:

• The selected route matches the user request
• New product repos were created through v0 unless explicitly exempted
• Existing repo changes are limited to the delegated repair/addition
• bun lint, bun test, or the repo's documented equivalents work when present

Example Interaction

User: "Set up my new product at ~/projects/my-saas"

Orchestrator Response:

Route: new Shipshit.dev product repo → v0.

npx @shipshitdev/v0 ~/projects/my-saas --agent codex --no-github

References

• references/legacy-manual-route.md - Manual workspace workflow
• references/templates/ - Code generation templates (NestJS service/controller/e2e specs, Better Auth guard/service/client, proxy.ts, React component/hook specs, frontend test setup with a mocked auth client)
• references/vitest.config.ts - Backend Vitest configuration (80% coverage, unplugin-swc)
• references/vitest.config.frontend.ts - Frontend Vitest configuration (jsdom)
• references/github-actions/ci.yml - CI/CD workflow
• references/architecture-guide.md - Architectural decisions
• references/coding-standards.md - Coding rules
• references/deployment-guide.md - Deployment guidance

Troubleshooting

Phase fails to complete

• Check if dependencies are installed (node, python3)
• Verify write permissions to project directory
• Check if conflicting configs exist

Linting errors after setup

• Run bun run lint:fix to auto-fix
• Check the root biome.json matches your stack
• Verify TypeScript config if using TS

Pre-commit hook not running

• Run bunx husky install manually
• Check .husky/pre-commit exists and is executable
• Verify prepare script in package.json

prisma generate or bun run build asks for DATABASE_URL

• The scaffold's api/prisma.config.ts reads process.env.DATABASE_URL directly, so generate and build work without a .env; only prisma migrate and the running API need the URL. Do not switch it to env("DATABASE_URL"), which throws when unset.