Skip to content
Viberia Docs

Your First Project

By the end of this page, you’ll have a working Viberia project with an HQ, a CodeForge building staffed by a Planner, Developer, and Reviewer, and a real task running end to end.

Prerequisites

Section titled “Prerequisites”
  • Viberia is installed and at least one CLI provider is configured. If not, finish Installation & Setup first.
  • You have a folder ready to use as your project root, or you’re happy to let Viberia create a sandbox folder for you at ~/Viberia/Tutorial-Demo/.

Note: The 14-scene tutorial that launches on first run does exactly what this page describes, automatically. If you want to watch the app drive itself, dismiss this page and let the tutorial run. If you’ve already seen the tutorial or you want to do it by hand, read on.

Choosing your path

Section titled “Choosing your path”

Viberia offers two ways to bootstrap a first project:

  • Guided path — you pick a folder on disk that already contains (or will contain) your work, and Viberia walks you through every step with explanations.
  • Quick path — Viberia spins up a sandbox project at ~/Viberia/Tutorial-Demo/ using a demo building so you can poke around without committing to a real folder.

Both paths converge on the same end state: a project on the world map with an HQ, a CodeForge, and an agent that has completed a task. The walkthrough below covers the guided path; the differences for the quick path are called out inline.

1. Create the project

Section titled “1. Create the project”

From the world map:

  1. Click the New Project button on the HudShelf (bottom of the screen).
  2. A modal appears asking for a project name and an optional folder path.
  3. Enter a name like Hello Viberia.
  4. Guided path: click Choose folder and select a directory on disk. Empty is fine; existing repositories are also fine — Viberia won’t touch files it doesn’t need to.
  5. Quick path: leave the folder field empty. Viberia will create ~/Viberia/Tutorial-Demo/ for you.
  6. Click Create.

The modal closes, the camera pans to an empty patch of map, and a labeled territory rises into view. That’s your project. You’ll see a tooltip prompting you to drop your first building.

Note: A project is always a 15×15 tile region. The folder path you chose is stored as the project’s working directory; agents in this project will treat it as their default cwd.

2. Drop the HQ

Section titled “2. Drop the HQ”

Every new project needs an HQ — the building that hosts the Dean, your per-project coordinator.

  1. The tooltip suggests dropping HQ. The HQ building kind is already selected for you. Move your mouse over the territory and you’ll see a placement preview.
  2. Click an empty tile near the centre of the territory.
  3. The HQ building drops into place with a short animation, and the Dean agent spawns inside.

If you’d rather pick the kind yourself, click the Buildings picker on the HudShelf and choose HQ from the list before placing it.

Note: HQ is special — it’s where you’ll later open project settings, change the folder path, manage project-wide skills and MCP servers, or delete the project. See HQ for the full tour.

3. Talk to the Dean

Section titled “3. Talk to the Dean”

Click the HQ building. The Building Window opens, showing the building’s agents and configuration. Click the Dean to open their Agent Window — a streaming chat panel.

Type a short message:

Hi! Quick overview of what this project is: it's a sandbox for me to learn Viberia.

Send it. You’ll see:

  • The Dean’s status indicator flip from idle to busy.
  • A streaming response appear character by character.
  • Tool call cards if the Dean decides to look at the folder you chose.

The Dean is your bridge between the Chief of Staff and the building agents you’ll add next. You don’t need it to do the work itself — its job is to know what’s in the project and to route requests appropriately.

4. Add a CodeForge

Section titled “4. Add a CodeForge”

A CodeForge is the engineering workspace: it ships with a Planner, a Developer, and a Reviewer wired into a standard PRD → implement → review flow.

  1. Close the Agent Window (the building stays open behind it).
  2. Click the Buildings picker on the HudShelf.
  3. Choose CodeForge.
  4. Click an empty tile in your territory, next to HQ.

The CodeForge drops onto the map and its three agents spawn inside. If you click the building, you’ll see all three listed.

Note: The quick path may have already placed a demo building for you. In that case, you can skip ahead — the demo building’s agents respond to the same first-task message described below.

5. Send a task via PRD handoff

Section titled “5. Send a task via PRD handoff”

Now you’re ready to do real work. The standard pattern in Viberia is PRD handoff:

  1. The Planner writes a Product Requirements Document.
  2. They hand it to the Developer with /handoff-prd-to-developer.
  3. The Developer implements it, optionally sending the result to the Reviewer with /send-to-review.

For this first task, we’ll keep it simple. The tutorial’s canonical first task is:

Add a button that says “Hello, Viberia”.

To run it:

  1. Click the CodeForge building, then click the Planner.
  2. In the Agent Window, type: 
    /draft-a-prd Add a button that says "Hello, Viberia" to the main page.
  3. The Planner runs the /draft-a-prd skill and produces a short PRD as a markdown file in your project folder. A Markdown Editor window opens so you can review it.
  4. When you’re happy with the PRD, ask the Planner: 
    /handoff-prd-to-developer
    The Planner sends the PRD to the Developer, who immediately starts work.
  5. The Developer reads the PRD, edits the relevant files, and reports back. You’ll see tool call cards for every file read and write.
  6. When the Developer finishes, switch to the Reviewer and run: 
    /send-to-review
    The Reviewer pulls up the diff, comments on quality, and gives a verdict.

You now have a real change in your project folder. Open the file in your editor of choice — or use Viberia’s built-in Markdown Editor or Terminal toolbox — to verify it.

Note: The slash commands above are skills. Viberia ships with a catalog you can browse, and you can install new ones via /learn-skill. See Skills for the full list.

What just happened

Section titled “What just happened”

In a single project, you’ve:

  • Created a territory rooted at a folder on disk.
  • Stationed a Dean to coordinate the project.
  • Added an engineering team (Planner, Developer, Reviewer) inside a CodeForge.
  • Run a PRD-driven workflow end to end with real file changes.

This is the basic pattern you’ll repeat for every project. From here you can:

  • Add more buildings (KnowledgeBase, WorktreeForge, Linear, MarketResearchers) — see Building Window and the Buildings section.
  • Try the Chief of Staff drawer to delegate from the portfolio level instead of one project at a time — see CoS Overlay.
  • Customize a Council or LoopReview building for multi-model deliberation or drafter-reviewer iteration.

If you got stuck

Section titled “If you got stuck”

Next: Settings Overview