Skip to main content

Create a project

A project is a workspace-scoped unit that owns an artifact tree. Server-side it maps to a storage prefix in the hosted service; client-side it's pinned by a waypoint.json index file at the root of your repository. A project belongs to exactly one workspace, and you can belong to multiple workspaces.

You create a project with the CLI, from inside the git repository you want Waypoint to manage.

Run waypoint init​

waypoint init --mode=<greenfield|characterize|rearchitect>

waypoint init is the onboarding orchestrator. Choose the mode that fits your situation:

  • greenfield — "Idea but no code yet." The agent walks personas → goals → features → architecture, writing one artifact at a time.
  • characterize — "Working codebase you want captured." The agent reads your existing code and proposes the full artifact tree, inferring intent.
  • rearchitect — "Product works but the implementation needs a redesign." The agent captures the product and intent and leaves architecture blank for redesign.

If you omit --mode, init auto-detects (a repo with no code files outside .waypoint/, .git/, and README is treated as greenfield; otherwise characterize) or prompts you.

What waypoint init sets up​

Running init does the following, in order:

  1. Confirms you're authenticated (you must have run waypoint login first).
  2. Resolves the onboarding mode (--mode, auto-detect, or prompt).
  3. Reads your git origin remote to infer the owner and repository name.
  4. Creates the project under your workspace on the server.
  5. Walks the GitHub App install if the binding isn't already mapped.
  6. Writes waypoint.json at the repository root — the manifest/index that pins each artifact by path and hash.
  7. Installs pre-commit and pre-push git hooks that run waypoint validate and upload artifact content.
  8. Registers Waypoint as an MCP server for every detected agent client (Claude Code, Cursor, Zed).
  9. Installs the mode-specific agent skill.
  10. Extends AGENTS.md with the Waypoint working block and writes WAYPOINT_USAGE.md.
  11. Prints the mode-specific next step.

init is idempotent — re-running it is safe. Use --force to overwrite a waypoint.json whose slugs differ from the current project.

tip

Project and workspace slugs. The project slug defaults to your lowercased git repository name; override it with --project. If you belong to a single workspace, it's selected automatically; multi-workspace users pass --workspace=<slug>.

The app renders your project​

If you started from the in-app onboarding walkthrough, the web app polls for your new project and switches into the project view as soon as init creates it server-side. You don't need to refresh or create anything in the UI — the first project is created by the CLI, not a web form.

note

A "New project" button does appear in the web app once a workspace already has at least one project, but the first project in a workspace is always created via waypoint init. What the magic-link sign-in provisions on the server (workspace, defaults) is handled for you; the walkthrough assumes you land in a workspace with zero projects.

With the project created and waypoint.json written, you're ready to author your first artifacts.