Skip to content

Greenfield: Your First Project

This guide walks you through creating a new project from scratch with the toolkit, from scaffolding to your first commit.

Have an existing project?

If you're adopting the toolkit for an existing codebase, see Brownfield: Adopting the Toolkit instead.

Prerequisites

Before starting your first project, make sure you have:

  • Claude Code CLI installed and authenticated — run claude --version to check, claude login to authenticate
  • Toolkit installed — run scripts/setup.sh --verify to confirm (see Installation)
  • A fresh Claude Code session — if you just ran the setup script, exit and restart Claude Code so it picks up the new skills
  • A Git repository to work in, or create a new one (mkdir my-project && cd my-project && git init)

Step 1: Initialize Your Project

Navigate to your project directory and start Claude Code:

cd my-project
claude

Or if you're using the VS Code extension, open the project folder in VS Code and open the Claude Code panel.

Then run:

/vt-c-scaffold

This asks for a project type — Product Development or Knowledge Work — then creates the complete project structure including CLAUDE.md, PRD.md, 00-inbox/, and type-specific directories.

You can also specify the type directly:

/vt-c-scaffold design my-app           # Product Development
/vt-c-scaffold knowledge market-research  # Knowledge Work

Already have a project?

Use /vt-c-0-start (development), /vt-c-pd-0-start (product design), or /vt-c-kw-0-start (knowledge work) to check an existing project's status and find your next step.

Step 2: Bootstrap Tech Stack (Development Projects)

For coding projects, add tech-stack configuration:

/vt-c-1-bootstrap

This adds CI/CD configuration, test framework setup, and language-specific tooling on top of the structure created by /vt-c-scaffold.

Step 3: Plan Your Feature

Before writing code, create an implementation plan:

/vt-c-2-plan

This orchestrates the SpecKit pipeline:

  1. Specify — Define the feature in a structured spec
  2. Plan — Design the architecture and approach
  3. Tasks — Break the plan into ordered, actionable tasks

The result is a specs/ directory with your feature's spec, plan, and task list.

Step 4: Build

With a plan in place, start implementation:

/vt-c-3-build

This guides you through executing the task list while capturing decisions in the session journal.

Step 5: Review

When implementation is complete, run the multi-agent review:

/vt-c-4-review

Six parallel reviewers check security, code quality, performance, patterns, testing, and documentation.

Step 6: Finalize

Before merging, run the final quality check:

/vt-c-5-finalize

This verifies security, migration safety, and compliance before release.

Two Paths: Design-First or Code-First

The guide above follows the code-first path — you have specs or know what to build and jump straight into implementation. For many projects, starting with product design gives better results.

If you're building a product where user research, a PRD, and prototyping would help:

/vt-c-pd-0-start

This starts the Unified Product Development workflow:

  1. /vt-c-pd-1-research — user interviews, personas, analysis
  2. /vt-c-pd-2-prd — create a Product Requirements Document
  3. /vt-c-pd-3-prototype — build a deployable prototype
  4. /vt-c-pd-4-validate — usability testing with real users
  5. /vt-c-pd-6-handoff — development handoff package

After handoff, generate specs and start development:

  1. /vt-c-specs-from-prd — generate implementation specs from the PRD
  2. /vt-c-activate — load specs, see the wave dashboard, pick a spec to build
  3. /vt-c-2-plan → /vt-c-3-build → /vt-c-4-review → /vt-c-5-finalize

Code-First (for technical projects)

If you already know what to build — an API, a CLI tool, an internal service — skip the design phases and go straight to planning:

  1. /vt-c-scaffold — create project structure
  2. /vt-c-1-bootstrap — add tech-stack configuration
  3. /vt-c-spec-from-requirements "describe your feature" — create a spec
  4. /vt-c-activate → /vt-c-2-plan → /vt-c-3-build → /vt-c-4-review → /vt-c-5-finalize

The Complete Journey

graph LR
    subgraph design["Design (optional)"]
        PD0["Start"] --> PD1["Research"] --> PD2["PRD"] --> PD3["Prototype"] --> PD4["Validate"] --> PD6["Handoff"]
    end

    subgraph specs["Spec Generation"]
        SFP["/specs-from-prd"]
        SFR["/spec-from-requirements"]
        ACT["/activate"]
        SFP --> ACT
        SFR --> ACT
    end

    subgraph dev["Development"]
        D2["Plan"] --> D3["Build"] --> D4["Review"] --> D5["Finalize"]
    end

    SCAFFOLD["/scaffold"] --> design
    SCAFFOLD --> SFR
    PD6 --> SFP
    ACT --> D2

Start with /vt-c-scaffold and choose your path. Design-first goes through the full product design workflow and then generates specs from the PRD. Code-first creates specs directly from requirements.