Skip to content

Generate a Team Repo

This guide covers creating a new team using the bm init interactive wizard, including post-generation setup.

Create a team

Run the interactive wizard:

bm init

The wizard will prompt you for:

  1. Workzone directory — where teams live (default: ~/.botminter/workspaces)
  2. Team name — identifier for your team (e.g., my-team)
  3. Profile — team methodology (e.g., agentic-sdlc-minimal)
  4. Bridge — communication bridge (e.g., Matrix via Tuwunel, the default) if the profile supports one
  5. GitHub integration — auto-detects your gh auth session, validates it, then lets you browse orgs and select or create a repo
  6. Project board — select an existing GitHub Project board or create a new one
  7. Members — optionally hire members during init (new repos only)
  8. Projects — select project repos from the same GitHub org (HTTPS-only, new repos only)

Existing repos

When selecting an existing repo, the wizard skips member hiring and project addition — the repo already has its own content. Use bm hire and bm projects add after init to modify the team.

What bm init does

For new repos:

  1. Detects GitHub auth — auto-detects your gh auth session; shows masked token for confirmation
  2. Validates credentials — calls gh api user to verify authentication before proceeding
  3. Creates team directory — {workzone}/{team-name}/team/ with git init
  4. Extracts profile — copies PROCESS.md, context.md (renamed to the agent's context file), knowledge/, invariants/, coding-agent/ from the profile on disk, filtering agent-specific content
  5. Hires members — if specified, extracts member skeletons into members/{role}-{name}/
  6. Adds projects — if specified, creates project directories and updates botminter.yml
  7. Creates initial commit — git add -A && git commit
  8. Creates GitHub repo — runs gh repo create and pushes (uses the validated token)
  9. Registers in config — saves team to ~/.botminter/config.yml (0600 permissions)
  10. Bootstraps labels — applies the profile's label scheme; stops with remediation commands on failure
  11. Creates/syncs GitHub Project — creates a new board or syncs Status field options on an existing one

For existing repos:

  1. Detects and validates GitHub auth — same as above
  2. Clones the existing repo — into {workzone}/{team-name}/team/
  3. Registers in config — saves team to ~/.botminter/config.yml (0600 permissions)
  4. Bootstraps labels — idempotent (uses --force)
  5. Creates/syncs GitHub Project — creates a new board or syncs Status field options on an existing one

Team name must be unique

bm init refuses to create a team if the target directory already exists. Choose a different name or delete the existing directory.

Non-interactive mode

For CI pipelines or scripted setup:

bm init --non-interactive \
  --profile agentic-sdlc-minimal \
  --team-name my-team \
  --org my-org \
  --repo my-team-repo \
  --project new

This runs the full init flow without prompts -- creates the GitHub repo, bootstraps labels, creates a Project board, and registers the team. Requires gh auth login or GH_TOKEN in the environment.

All required parameters must be provided as flags. See the CLI reference for the full parameter list.

Post-generation setup

1. Push to GitHub (if not done during init)

Members coordinate through GitHub issues, so the repo needs a GitHub remote:

cd ~/workspaces/my-team/team
gh repo create my-org/my-team --private --source=. --push

2. Hire team members

bm hire architect --name bob
bm hire human-assistant --name alice

See Manage Members for details.

3. Add projects

bm projects add https://github.com/org/my-project.git

Note

Project URLs must be HTTPS. SSH URLs are not supported.

4. Provision workspaces

bm teams sync

This creates workspace repos for each member with the team repo as a team/ submodule, project forks as projects/ submodules, copied context files (PROMPT.md, CLAUDE.md, ralph.yml), and assembled .claude/agents/.

5. Add project-specific knowledge

Populate projects/<project>/knowledge/ with domain-specific context:

cd ~/workspaces/my-team/team
cp ~/docs/architecture.md projects/my-project/knowledge/
git add projects/my-project/knowledge/architecture.md
git commit -m "docs: add project architecture knowledge"

Available profiles

Use bm profiles list to see all available profiles:

Profile Description Status
agentic-sdlc-minimal Minimal agentic SDLC with three roles (engineer, chief-of-staff, sentinel) Available
scrum Multi-role team with pull-based kanban, status labels, conventional commits In development

agentic-sdlc-minimal supports communication bridges: Matrix via Tuwunel (default), Telegram (experimental), and Rocket.Chat (experimental). Select one during bm init or use --bridge <name> in non-interactive mode. See the Bridge Setup Guide for details.

Use bm profiles describe <name> for detailed information about roles and labels.