Your first project

This page starts from an installed rafa and takes one repository from nothing to a plan you can run. If rafa --version does not answer yet, start at Install. It also assumes you have read Before you run it.

1. Set up the project

At the root of the repository you want to work on, run the command below. If you already ran it on the Install page, running it again changes nothing and says so.

rafa init

On a terminal, init asks which folder is the project's root: the git top level, or the outermost monorepo root above it. --yes takes the first candidate, and --root=<path> names one. Then it writes what is missing. On a fresh repository with no GitHub remote, rafa init --yes --no-board printed:

Initialised a rafa project at <your repository> (the git toplevel).
  created   .rafa/
  created   .rafa/config.yaml
  created   .rafa/specs/
  created   .rafa/plans/
  created   .rafa/runs/
  created   .rafa/effort/
  created   .rafa/instincts/
  created   .gitignore
…

.rafa/config.yaml holds every setting commented out at its default, so the project runs on the defaults until you uncomment a line. The .gitignore gains a block that keeps .rafa/ out of git. In your home folder, init also writes ~/.rafa/config.yaml, the settings every project on the machine reads.

On a GitHub repository, init ends by offering to set up the board: labels, a spec issue template and a pinned Roadmap issue. You can skip it now; rafa init --board sets it up later, and Specs and plans says when you need it.

2. Check the project is ready

rafa doctor

doctor runs every check rafa loop start runs before its first session, and starts nothing. On a ready project with no plan yet, it ends with:

Preflight passed: rafa loop start would go on to its first session.
…
Effort sync: ok, local

A missing tool or login is named here, before any session is paid for. rafa doctor --deep goes further and reads what a loop session can reach: its settings, PATH, providers and the tools the stack needs.

3. Write a spec

A spec says what you get, where things stand, the design, what can go wrong, the tasks the plan must carry, and how you will know it is done. For a first plan, keep it a file: save it as .rafa/specs/my-feature.md. rafa's repository has the template and a prompt for drafting one.

4. Turn the spec into a plan

rafa plan create --spec=.rafa/specs/my-feature.md

This starts one Claude Code session, which reads the spec and the repository and writes a checklist the loop can parse. The plan lands in .rafa/plans/PLAN-my-feature.md. When something must be true before the run, a PREREQUISITES-my-feature.md file sits beside it.

rafa plan show my-feature

Read both files before you run anything. A plan is plain markdown, so edit a task, drop one or add one.

Next

The cycle runs the plan through the loop and lands its pull request.