Adding RepoOS to an existing repo

RepoOS is designed to drop into a repo you already have. repoos init is idempotent — it never overwrites an existing file, only creates what's missing — so it's safe to run on an established project.

What repoos init adds

From the root of your repo:

repoos init

By default, RepoOS files live under a repoos/ subdirectory to keep metadata out of your project source. You can choose a different location or explicitly pick the repo root during the interactive prompt.

It creates only what isn't already there. With the default layout:

Path	What it is
repoos.toml	Configuration. Every field is optional. Always at the repo root.
repoos/work/	One markdown file per task. This is the board. Includes 0001-set-up-repoos.md (a done example) and an inbox starter task.
repoos/docs/	Context an agent needs to work on this project — architecture notes, decisions, history.
AGENTS.md	Instructions agents read first. The cross-tool standard; Claude Code, Codex, Cursor, Aider and Zed all read it. Always at the repo root.
.env.example	Names of secrets a fuller setup expects. No values.
.gitignore	Created, or appended when one already exists. Ignores the derived cache, root .repoos/ runtime state, .env, .env*.local, node_modules/, task and input attachment directories, and .DS_Store.
repoos/.repoos/canary.txt	Tracked canary counter.

On an existing repo the inbox starter is 0002-read-the-codebase.md (read this codebase and propose repoos/docs/ plus an initial backlog). Promote it with repoos mv 0002 ready when you want it picked up. A brand-new project seeds 0002-flesh-out-the-vision.md instead, runs git init, and unless you pass --no-commit commits the scaffold (chore: initialize RepoOS project). Init in an existing repo does not make that commit.

With the default layout, repoos.toml persists the configured paths:

workDir    = "repoos/work"
docsDir    = "repoos/docs"
skillsDir  = "repoos/skills"
storiesDir = "repoos/stories"
inputsDir  = "repoos/inputs"
cacheDir   = "repoos/.repoos"

If .gitignore already exists, it is only appended to for the RepoOS ignore lines that are missing. An existing AGENTS.md is never overwritten: in an interactive terminal, repoos init previews a small RepoOS guidance section and adds it only if you explicitly approve it. Non-interactive runs leave it unchanged. Re-running repoos init reports "already set up" and changes nothing else.

Choosing a layout

During interactive repoos init, you'll be prompted:

Where should RepoOS files live? [repoos/]

• Enter accepts the default repoos/ subdirectory.
• Type a custom path like .meta/repoos/ to nest it elsewhere.
• Type / to place work/, docs/, and .repoos/ at the repo root (the original layout).

repoos.toml and AGENTS.md always stay at the repo root regardless of the layout choice.

Defining your areas

In an interactive terminal, repoos init also offers to seed the task-area vocabulary that powers the drawer's area picker and the PM prompt:

Task areas to seed the area picker — comma-separated (e.g. web, cli, api; Enter to skip):

Type names (or press Enter to skip) and RepoOS appends real [[areas]] rows to your existing repoos.toml. If you give areas, it then asks whether to scaffold commented [[preview.targets]] stubs for them, since preview targets route by area and the two are usually set up together. Both prompts are skippable, and a repo that already declares any [[areas]] is never asked again. You can edit the list later in Settings → General → Areas or by hand — see Configuration.

What it doesn't touch

Your source, your package.json, your build pipeline, and your existing docs are all untouched. RepoOS adds a few directories and a local server that reads them; it isn't a hosted service and it doesn't ask you to move your work anywhere.

If your project uses a build pipeline RepoOS doesn't recognise, the checks degrade gracefully rather than failing you for not looking like RepoOS.

Adopt incrementally

You don't have to move your whole roadmap at once:

1. Run repoos init and commit the scaffolded files. AGENTS.md is what agents read first, so getting it into the repo is what makes agents useful here.
2. Add a handful of tasks with repoos new and work them through the lifecycle.
3. Grow repoos/docs/ as you go — each durable decision you write down once stops being re-derived on every future task. See Concepts.

Running it outside a git repo

Run repoos init in a directory that isn't inside a git repo and it switches to a guided flow for a brand-new project instead: it can create the project in a subdirectory, offer a repo-root or repoos/-subfolder layout, take a one-line description, and optionally make the initial commit. That description is embedded in the starter task ("Flesh out the product vision and initial architecture"), so the first thing on the board is turning it into a real vision, architecture notes and a follow-on backlog.

Starting a brand-new project with an agent?

Don't git init first — that makes repoos init see an existing repo and seed the wrong starter. See Starting a new project as an agent for the non-interactive recipe and pitfalls.

Next

repoos serve     # local control plane, plus background agents — check first
repoos new "Fix the login redirect loop"

Before repoos serve, check which agents are enabled. Serve starts the web UI and API, and background automation. The CTO board monitor ticks every 5 minutes (ctoMonitorIntervalMs, default 300000). When the cto agent has enabled = true, that tick launches a coding agent. Turn it off with enabled = false on that [[agents]] row. The built-in default leaves the CTO disabled. The reviewer is on by default and starts when a task enters review. The watchdog (watchdog.enabled, default true) can restart a stalled engineer.

Then see Install and first task for the lifecycle, or Configuration for repoos.toml.