rafa init

rafa init sets up a project once, and is safe to run again: it writes only what is missing or stale, and says so. Your first project shows a first run.

Spends: nothing. Changes: .rafa/ and its config, the .gitignore block, ~/.rafa/config.yaml; on GitHub, when you answer yes, labels, the spec template, a pinned Roadmap issue, the epic guard workflow and a GitHub project. Needs: git; gh signed in for the board, with the project scope for the GitHub project; see Prerequisites.

Reference: rafa init

Set up a rafa project: its root, .rafa/config.yaml, the tree and the .gitignore entry.

rafa init [--root=<string>] [--yes] [--board] [--epic-guard] [--project]
  [--release]

Sets up a rafa project. On a terminal it lists the root candidates, the git toplevel or the working directory outside a repository and then the outermost monorepo root above it, each refused one with its reason, and reads a candidate number or a path typed freely. --root=<path> names the root instead, absolute or relative to the working directory, and --yes takes the first candidate; without a terminal one of the two is needed. Under the root it writes .rafa/config.yaml with every setting commented out at its default, the tree specs/, plans/, runs/, effort/ and instincts/ under .rafa/, and the rafa block in .gitignore from the tracking settings; under the home it writes ~/.rafa/config.yaml and ~/.rafa/instincts/ when they are missing. Only what is missing or stale is written, so a rerun changes no byte and says so. It warns when ~/.rafa/bin is not on PATH ahead of ~/.bun/bin, and when a plan under plan.dir routes to an agent that resolves only in ~/.claude/agents and rafa does not ship, naming rafa agent vendor <name>; it writes nothing under .claude/ itself. A repository whose pull request provider is gh ends with one question about setting up the GitHub board, which --board and --no-board answer for a script, and then, once the board has run, one question about installing the epic guard workflow .github/workflows/epic-guard.yml, which removes a second epic: label from an issue and comments why; --epic-guard and --no-epic-guard answer that one. When board.relationships is set, the board is then read for relationships held in the other mode: every write that moves them into the configured one is printed and a terminal is asked once, nothing is written on a no, and once every write went through a second question asks whether to remove the old marks. Last, once the board has run, one question asks whether to copy the GitHub project template to the repository's owner, link it, add the issues and fill their fields; --project and --no-project answer that one. Adding the issues, reading their facts and writing their fields each print a start line with the total, a progress line at most every board.project.progressSeconds and an end line, one progress event each with --output=json. On a terminal it also asks once whether every pull request bumps the version and gains a changelog entry, and writes the answer as release.enabled; --release and --no-release answer that one, and --yes leaves it unset. With --output=json the root and every path checked are the data of the terminal result event.

Flag	Type and default	What it does
--root	string	The project root, absolute or relative to the working directory. No candidate is listed.
--yes	boolean	Take the first root candidate without asking: the git toplevel, or the working directory.
--board	boolean	Set up the GitHub board without asking: the labels, .github/ISSUE_TEMPLATE/spec.md and a pinned Roadmap issue named by roadmap.issue. --no-board leaves it alone. Without either, a terminal is asked once and a run with no terminal leaves it alone.
--epic-guard	boolean	Install the epic guard workflow without asking, once the board has run: .github/workflows/epic-guard.yml, which removes a second epic: label from an issue and comments why. --no-epic-guard leaves it out. Without either, a terminal is asked once and a run with no terminal leaves it out. A file already at that path is left as it is.
--project	boolean	Create the GitHub project without asking, once the board has run: copy board.project.template to the repository's owner, link the repository, add its issues, fill their fields and save board.project.number. --no-project leaves it out. Without either, a terminal is asked once and a run with no terminal leaves it out. The adds, the facts reads and the field writes print their progress, as adding issues: 146/283, 6m 40s.
--release	boolean	Write release.enabled: true without asking, so every pull request bumps release.versionFile and gains a release.changelog entry. --no-release writes false. Without either, a terminal is asked once, and --yes or a run with no terminal leaves the setting unset at its default auto.

Examples:

• rafa init: On a terminal, lists the root candidates and reads a candidate number or a path.
• rafa init --yes: Takes the first candidate: the git toplevel, or the working directory outside a repository.
• rafa init --root=../my-monorepo: Sets up the project at the root named, asking nothing.
• rafa init --yes --release: Takes the first candidate and writes release.enabled: true, asking nothing.
• rafa init --yes --board: Takes the first candidate and sets up the GitHub board without asking: the labels, the spec issue template and a pinned Roadmap issue. Each part already there is left as it is.
• rafa init --yes --board --epic-guard: Sets up the GitHub board and installs the epic guard workflow, asking nothing.
• rafa init --yes --board --project: Sets up the GitHub board and its GitHub project, asking nothing. A second run writes nothing.

Output formats: text, json.