Project Init Orchestrator

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

Authorized Scope

Apply this engine only within the user's requested task and existing explicit authorization. Loading or delegating to it grants no additional authority. Preserve report-only restrictions and the caller's target, host, provider, and cost limits. Existing approval satisfies a gate only for the same actions and scope; obtain approval before expanding them. 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
• Desired app surfaces, routes, agent platform support, and GitHub setup

Outputs:

• Selected initialization route
• List of delegated skills or v0 command used
• Files/directories created or modified
• Verification status and remaining manual setup

Creates/Modifies:

• New product repos through npx @shipshitdev/v0
• Existing repo .agents/, .claude/, .codex/, lint, test, and scaffold files when delegated

External Side Effects:

• May install dependencies 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
• Before overwriting existing agent/config files

Delegates To:

• fullstack-workspace-init for v0-backed Shipshit.dev product scaffolding
• agent-folder-init for existing repos that only need AI project context
• linter-formatter-init, testing-cicd-init, and husky-test-coverage for repo repair
• 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

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

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

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

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 .eslintrc.js 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