Usage

repo generates a repository for spec-driven development from one file, .repo.yaml, at the repository root. The developer edits it; repo update applies it.

Commands

Command	Effect
repo init	Writes a commented .repo.yaml template for a single repository
repo init-mono	Writes a commented .repo.yaml template for a mono-repository with two artifacts
repo add	Appends an empty artifact to the .repo.yaml of a mono-repository; generates nothing
repo update	Generates the repository, or refreshes its generator-owned files
repo check	Lists every file repo update would change, and fails if there is one
repo version	Prints the version

Commands take no options and work on the current directory. The full description is cli.yaml.

A typical start:

git init
repo init        # or repo init-mono
# fill in .repo.yaml
repo update

repo update and repo check require a Git working tree; repo update requires it to be clean apart from .repo.yaml.

.repo.yaml

name: Example Robot
description: Three-wheeled omni-drive robot.
repository: gitlab.com/<group>/<project>
repoType: mono
ci: gitlab
assistants: [claude]
artifacts:
  - name: motor-controller-bridge
    title: Motor Controller Bridge
    description: Relays drive messages between CAN and the motor controller boards.
    language: cpp
    type: firmware-stm32

Field	Meaning
name, description	Name and one-sentence description of the repository
repository	Path at the host without scheme, e.g. gitlab.com/<group>/<project>; the Go module path, Java package, and registry derive from it
repoType	single: one artifact at the root; mono: one artifact per subdirectory
ci	gitlab or github
assistants	claude, copilot, both, or none
artifacts[].name	Slug for executable, image, tag prefix, and, in a mono-repository, directory
artifacts[].title, description	Name and one-sentence description of the artifact
artifacts[].language, type	The profile; see Profiles
artifacts[].modules	The modules to generate; without it, the defaults below
artifacts[].registry, port	Optional container registry and Compose host port
meta	Written by repo update only

The schema is repo-config.schema.json.

Modules

Module	Generates	Default
scaffold	Source and test tree, build files, Makefile, Devbox, lint configuration	On
ci	CI pipeline, cliff.toml, CHANGELOG.md	On; needs scaffold
specs	specs/ with the templates, mkdocs.yml	On
domain-model	specs/functional_design/domain_model.md	On for services; needs specs
bdd	BDD harness and test/bdd/	On, except for electronics; needs scaffold
manual-test	test/manual/ with the manual test template	On for firmware and electronics
ai	CLAUDE.md, .claude/, Copilot files, per assistants	On
guidelines	A copy of the profile's guidelines in guidelines/	Off

Without module guidelines, a repository links to the guidelines of this site.

Files the Generator Owns

repo update overwrites the files the generator owns, such as .claude/rules/, the CI pipeline, the Makefile, and the templates in specs/, on every run. It writes the files the developer owns, such as README.md, CLAUDE.md, the source code, and the specifications, only when their module is new. It deletes nothing; for a module or artifact removed from .repo.yaml, it lists the files it no longer generates.