Skip to content

Latest commit

 

History

History
138 lines (111 loc) · 11.9 KB

configuration.md

File metadata and controls

138 lines (111 loc) · 11.9 KB

Configuration

Every file here is per-deployment and gitignored; make setup creates them.

config.json

Project-specific configuration (gitignored, created by make setup). Keys:

  • project.name: Project name (e.g. brave-core)
  • project.org: GitHub organization (e.g. brave)
  • project.prRepository: PR repository as owner/repo (e.g. brave/brave-core)
  • project.issueRepository: Issue repository as owner/repo (e.g. brave/brave-browser)
  • project.defaultBranch: Default branch for the PR repo (e.g. master)
  • project.targetRepoPath: Path to the target git repo (relative to the bot dir, to its parent, or absolute — all three resolve). . is the self-hosted case: the target repo is the bot directory, so the loop develops itself. That needs a profile with "worktrees": true, because every cron job's prologue hard-resets the bot directory onto its default branch and would throw away work left in it
  • project.prdMode: curated (default) — data/prd.json is authored and is the source of truth for what the bot works on; a run never rewrites it, and the scheduled scripts/sync-prd.sh only appends stories for newly assigned issues. auto — the PRD is a cache with no manual curation: run.sh rebuilds it from assigned issues and open bot PRs before each run, and retires the stories whose PR has been merged since the last one, so a landed PR does not hold a place in the queue that outranks pending work. It also retires a pending story with no PR whose issue has since been closed, which nothing else notices because intake only ever asks GitHub for open issues. Either way the sync is plain Python against the GitHub API (no agent, no tokens)
  • project.profile: Which projects/<name>/ profile supplies this project's rules — validation steps, test targets, and the project-specific docs the workflows point at. Omitted means brave-core (every deployment predating profiles is one); new setups get the profile named after the project when one exists, else default. Leaving it at default while projects/<project.name>/ exists is refused: run.sh stops and says which line to change, because a profile nobody chose produces wrong work rather than no work
  • project.useFork: true (default) — the bot pushes branches to its own fork (origin = fork, upstream = PR repo). false — the bot has write access to the PR repo and pushes there directly (origin = PR repo, no fork). Set false only when the bot account is a collaborator on the PR repo; make setup will then stop expecting a fork and stop offering to create one
  • bot.username: Bot's GitHub username
  • bot.email: Bot's email for git commits
  • bot.sshKeyPath: SSH identity the bot pushes with (null = this machine's default key). See Bot identity
  • bot.signingKeyPath: public key the bot signs commits and tags with (null = the same key it pushes with, bot.sshKeyPath). Signing with any other key — including the machine owner's — makes GitHub mark every bot commit Unverified. The key must also be registered on the bot's GitHub account as a signing key; authentication keys are a separate list
  • bot.ghAccount: gh account whose token the bot uses (null = same as bot.username)
  • bot.ghConfigDir: isolated gh config directory for the bot (null = use ~/.config/gh). Set this to keep the bot's GitHub login out of your personal gh config entirely — no account is added, switched, or made active outside this repo. Create it with GH_CONFIG_DIR=<dir> gh auth login
  • reviewer.username: the second GitHub account whose review ./run.sh waits for on each pull request it pushes to (null = none, no wait). The reviews are posted by https://github.com/brave-experiments/reviewer. Must not be bot.username. See Review gate and Reviewer account
  • reviewer.ghConfigDir: the reviewer's own gh config directory (null with a username set = ~/.config/gh-<username>, or under $XDG_CONFIG_HOME). make setup creates it and walks you through logging in
  • reviewer.maxRounds: how many reviews of one story ./run.sh waits for before giving up on it (default 5; 0 turns the wait off). A review that asks for changes starts a fix round and another wait. Has no effect without reviewer.username. See Review gate
  • reviewer.waitMinutes: how long ./run.sh waits for one review before moving on (default 120). The reviewer answers on its own schedule, so this must outlast the review-request poll plus a review
  • bot.agent: Which agent ./run.sh runs, claude (default), codex, cursor, or bravebot. make setup asks. make schedules reads it when installing, so a run.sh cron line carries --agent <name> --agent-bin <absolute path> for anything but claude; re-run it after changing the agent
  • bot.maxConcurrentRuns: How many run.sh instances may share this bot directory (default 1). Above 1 requires a profile with "worktrees": true — without per-story worktrees two runs share one working tree and overwrite each other. See Concurrent runs
  • bot.concurrentJobs: How many runs one ./run.sh starts in parallel, each on a run slot of its own (default 1: one invocation is one run). Cannot exceed bot.maxConcurrentRuns, and does not apply to tui mode, which runs one job. See Starting several runs at once
  • bot.claudeModel: Claude model to use (opus, sonnet, etc.; overridden by ./run.sh --model for Claude runs)
  • bot.claudeBin: Path to the claude binary (null = found on PATH)
  • bot.codexModel: Codex model to use (null = Codex default; overridden by ./run.sh --model for Codex runs)
  • bot.codexBin: Path to the codex binary (null = found on PATH)
  • bot.cursorModel: Cursor model to use (null = account default; overridden by ./run.sh --model for Cursor runs)
  • bot.cursorBin: Path to the cursor-agent binary (null = found on PATH)
  • bot.bravebotModel: model for --agent bravebot (null = the agent's own choice; overridden by ./run.sh --model).
  • bot.bravebotBin: absolute path of the binary for --agent bravebot. make setup stores it, because that binary is a #!/usr/bin/env node script that usually lives under nvm, which cron's PATH does not have (null = found on PATH; ./run.sh --agent-bin overrides it for one run). make schedules also puts its directory on the cron block's PATH so the shebang finds node
  • labels.*: legacy. Labels now live in the project profile (projects/<name>/profile.json); labels.disabledTestLabel and labels.inProgressLabel are still honoured as fallbacks for deployments that set them by hand. See Project profiles
  • labels.inProgressLabel: label marking an issue as being worked, so deployments on other machines skip it ("" = off, the profile's labels.inProgress wins where it defines one). See Concurrent runs
  • bestPractices.docsDir: Path to the docs directory containing best practices (relative to bot dir)

A config.example.json template is included, plus a reference config per shipped deployment: config.brave-core.json and config.brave-dev-loop.json (this repo developing itself). Copy one over config.json to skip the wizard.

data/prd.json

Product Requirements Document defining user stories and acceptance criteria.

  • stories[].id: Unique story identifier
  • stories[].priority: Execution order (1 = highest), and the last tiebreak once the triage axes have been read
  • stories[].triage: The issue's triage axes, {"importance": 1-5, "urgency": 1-5, "size": 1-5}, with any axis nobody has judged left out. Read off the issue's labels by the backlog sync and used to order pending work — see Backlog order. Absent on every story in a project whose profile defines no labels.axes
  • stories[].status: Story state
  • stories[].branchName: Git branch name (set when work starts)
  • stories[].prNumber: PR number (set when PR created)
  • stories[].prUrl: PR URL (set when PR created)
  • stories[].lastActivityBy: Who acted last — "bot" | "reviewer" | null
  • stories[].acceptanceCriteria: Test commands that must pass

data/progress.txt

Log of completed iterations:

  • Codebase Patterns section (reusable patterns discovered during development)
  • Per-iteration entries with status transitions, files changed, test results
  • Learnings for future iterations

.claude/CLAUDE.md

Agent instructions defining workflow, testing requirements, git operations, security guidelines, and quality standards.

Run State Configuration

data/run-state.json controls per-run behavior. With several run slots, the settings below are still read from this one file and copied into each slot's data/run-state.slot-N.json at run start; the iteration state (runId, storiesCheckedThisRun, ...) is per slot. See Concurrent runs.

Field Description
runId Timestamp when this run started (auto-set)
storiesCheckedThisRun Story IDs already processed in this run
skipPushedTasks Skip all "pushed" PRs, only work on new development
lastIterationHadStateChange Tracks if work was done last iteration

Archiving

When the branch changes between runs, previous state is automatically archived:

archive/
  └── 2026-01-30-old-branch/
      ├── data/prd.json
      └── data/progress.txt

Finished stories are archived too, but only where project.prdMode is auto. There, prd.json is a cache rebuilt from GitHub at the start of every run, so a merged or invalid story left in it is only something for the selector to filter and a reader to scroll past: run.sh moves it to prd.archived.json before any work is selected. The syncs read that file as well, so nothing that moves there is ever re-added as fresh work. A curated PRD is the operator's own list and is archived on the operator's say-so — make archive-prd.

Worktrees between runs

Where the profile sets "worktrees": true, each story gets its own ../<repo>-<issue> checkout, and each of those grows a build directory that can reach several gigabytes. run.sh collects them itself, so the disk does not fill with the build output of work that has already landed:

  • at the end of a session, every worktree nothing is using
  • at the start of the next one, the same but only those idle over 24 hours, since another run may be mid-iteration in one it used minutes ago

scripts/clean-worktrees.py decides, and keeps anything that would lose work: uncommitted changes, a detached worktree whose commits no ref keeps, a worktree a live run claims, or one git has locked. Commits on a branch are none of those — the branch is the repository's, so it outlives the worktree and the report names it as the worktree goes. Idleness is measured from the last git command run in the worktree, not from when it was added — a long-lived story's worktree is days old and still in use. --dry-run reports without removing. A story whose worktree was collected re-creates it from origin/<branch> on its next iteration, or from the local branch where nothing was pushed.

To empty the directory by hand rather than wait for a run to collect:

make unmount-worktrees            # every worktree idle for over 24 hours
make unmount-worktrees ALL=1      # every worktree, whatever it holds
make unmount-worktrees DRY_RUN=1  # report only

ALL=1 is the one that ignores the guards above, and uncommitted changes are all it can lose — it names each worktree holding some as it removes it. Branches belong to the repository rather than to the worktree checked out on them, so commits no remote has survive, and git checkout <branch> in the main checkout still finds them. A worktree a live run claims, or one git has locked, is kept either way: deleting the directory under a running session breaks it. No model is involved in any of the three.