Set up a Project

Run vago init in a repo to get the starter Workflows and skills, keep them current with vago update, and pick a Workflow.

A Project is the repo Vago works on. Setting one up copies Vago’s starter Workflows, their prompts and scripts, and a set of skills into it. Every vago command reads the directory it runs in as the Project, so run them from the repo’s root.

Run vago init

cd ~/code/my-app
vago init

vago init first asks Commit the Workflow? [y/N], then writes:

.vago/workflows/small.toml and .vago/workflows/try-hard.toml, the two starter Workflows.
.vago/prompts/, the prompt of each agent Step, and planning.md, the instructions of the agent that plans a Goal with you in the TUI.
.vago/scripts/, the shell scripts the starter Steps run: branch.sh cuts a Ticket’s branch, merge.sh squash-merges it and opens the Goal’s PR, ready.sh labels that PR ready-for-review and mentions you on it.
Seven skills in .claude/skills/, where Claude Code finds them, and the same seven in .agents/skills/, where Codex finds them, so the starter prompts work on either Harness.

The skills are the ones the starter prompts name, and you can use them in your own sessions too:

vago-write-code, vago-check-red-flags and vago-design-module hold the code and design rules, from John Ousterhout’s A Philosophy of Software Design.
vago-pr writes a PR body as a summary, evidence and merge danger. The starter’s describe Step runs it on the Goal’s PR.
vago-grilling, vago-to-goal and vago-to-tickets plan a Goal. In a session of your own, /vago-grilling questions you about an idea, /vago-to-goal writes the conversation up as a Goal, and /vago-to-tickets splits that Goal into Tickets with the vago CLI.

Answer y to the question to leave .vago/ and the skills for git, so everyone who clones the repo gets your Workflows. Any other answer adds .vago/ and each skill’s folder to .git/info/exclude, so they stay in your checkout and never show up in git status. Either way it adds .vago-goals/, where your Goals and Tickets live, to .git/info/exclude: Goals and Tickets are never tracked by git.

vago init refuses, and changes nothing, outside the root of a git repo, or when a file it would write already exists in .vago/, .claude/skills/ or .agents/skills/.

Keep it current with vago update

After you upgrade vago, run vago update in each Project to bring .vago/ and both copies of the skills to the starter the new binary ships:

vago update

It overwrites each starter file that differs, writes the ones that are missing, and prints the path of every file it changed, so you can see when it replaced a prompt you had tuned. Files you added, such as your own Workflow, prompt or skill, stay as they are, and so does every Goal in .vago-goals/. It keeps the answer you gave vago init: when .git/info/exclude lists .vago/, a skill new in this starter is excluded too. Run it twice and the second run prints nothing.

Pick a Workflow

Each Goal names the Workflow its Tickets go through, so you pick one when you create the Goal. Both starters run every Ticket through these Steps in order, on Claude Code with Claude Opus:

Workflow	Steps	Pick it when
`small`	New branch, Build, Checks, Review, Goal review, Squash merge	The Tickets are small and already clear. One agent builds each Ticket and a fresh one reviews it.
`try-hard`	New branch, Design, Product, Architecture, Design choices, Build, Checks, Review, Goal review, Squash merge	A Ticket leaves design questions open. Agents propose designs, check them against the Ticket, pick one, and write down the choices before one builds it. It takes four more agent Runs per Ticket than `small`.

Goal review runs only on the Goal’s last Ticket, and reads the whole Goal’s diff. Once every Ticket is done, both starters write the PR’s description and mark it ready for review.

The starter files are yours to change. Read them before your first Goal, since they assume a few things about the Project:

The Checks Step runs bun run check, and the prompts tell every agent to make it pass. In a Project with another check command, change it in .vago/workflows/*.toml and in the prompts that name it.
merge.sh pushes the Goal’s branch to origin and opens its PR with gh, against the repo’s default branch.
The prompts send agents to the docs that the Project’s AGENTS.md names.

Each Workflow is one TOML file in .vago/workflows/, and the file’s name, without .toml, is the name you pass to --workflow. Copy one to make your own.

Next: Your first Goal.

This page as Markdown