Getting Started

This guide walks you through setting up your own Claude Code agents, hiring a member, and launching it. Familiarity with Git, GitHub, and command-line tools is assumed.

Prerequisites

Make sure you've completed the Prerequisites setup — tools, recommended environment, and gh authentication — before proceeding.

Step 1: Create a team

Run the interactive wizard:

bm init

The wizard walks you through the full setup:

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 — optional communication bridge (Matrix or Telegram) 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 interactively
6. Project board — select an existing GitHub Project board or create a new one
7. Members and projects — optionally hire members and add project fork URLs right away

What bm init does

When the wizard completes, it has:

• Created (or cloned) a team repo — the control plane with your profile's process conventions, knowledge structure, and role definitions
• Bootstrapped GitHub labels — status labels matching the profile's workflow pipeline (e.g., status/eng:dev:implement, status/eng:po:triage)
• Created (or selected) a GitHub Project board — for tracking issue status across roles
• Registered the team in your local config (~/.botminter/config.yml)
• Hired members (if you chose to during the wizard) — extracted member skeletons into the team repo
• Added projects (if you chose to during the wizard) — registered project fork URLs in the team config

Config is saved early so that if a GitHub operation fails, the team is still registered and recoverable. If any GitHub operation fails, the wizard stops with actionable error messages showing the exact gh commands to run manually.

workzone/
  my-team/
    team/                           # Team repo (control plane, git repo)
      botminter.yml                 # Profile manifest (roles, statuses, views)
      PROCESS.md                    # Issue format, labels, communication protocols
      CLAUDE.md                     # Team-wide agent context (name varies by coding agent)
      knowledge/                    # Team-level knowledge files
      invariants/                   # Team-level quality rules
      coding-agent/
        skills/                     # Shared agent skills (gh CLI wrapper)
      skills/                       # Profile-level skills (knowledge-manager, etc.)
      formations/                   # Deployment targets (local, k8s)
      projects/                     # Project-specific knowledge and invariants
      members/                      # Member configurations (populated if you hired during init)

Step 2: Hire members and add projects

If you already hired members and added projects during bm init, skip to Step 3.

Hire a member

Add a member to the team by specifying a role from the profile:

bm hire engineer

This extracts the member skeleton from the profile on disk into the team repo — including its Ralph config, prompts, knowledge, and invariants. With the agentic-sdlc-minimal profile, the engineer role is an agent that wears all hats (PO, architect, developer, QE).

You can optionally provide a name:

bm hire engineer --name atlas

To see what roles are available in your profile:

bm roles list

Add a project

Register a project fork for your agents to work on:

bm projects add https://github.com/my-ai-team/my-project-fork

This tells BotMinter which codebase your agents will clone and work in. The URL should point to a fork of your project (see Prerequisites — repo layout).

bm projects add also creates a project/<name> label on the team repo (e.g., project/my-project-fork). This label is how agents know which issues belong to which project.

Step 3: Provision workspaces

Once you have members hired and projects added, provision the workspaces:

bm teams sync --repos

This is where the setup becomes real. bm teams sync does the following for each hired member:

• Pushes the team repo to GitHub (with --repos) so agents can coordinate via issues
• Creates a workspace directory per member × project
• Clones the project fork into the workspace
• Adds the team repo as a team/ submodule inside the workspace repo
• Copies context files — copies PROMPT.md, CLAUDE.md, and ralph.yml from the team submodule to the workspace root
• Assembles .claude/agents/ — merges agent definitions from team/ submodule paths via symlinks

If you've already pushed the team repo, you can run bm teams sync without --repos.

Step 4: Set up the Project board

Sync the GitHub Project board's status columns with your profile and get instructions for creating role-based views:

bm projects sync

This updates the board's Status field options to match your profile's workflow stages, then prints step-by-step instructions for creating filtered views so each role sees only the statuses relevant to it.

Example output for the agentic-sdlc-minimal profile:

✓ Status field synced (25 options)

Your GitHub Project board needs role-based views so each role sees
only its relevant statuses. Create one view per role listed below.

Open the board: https://github.com/orgs/my-ai-team/projects/1

For each view:
  1. Click "+" next to the existing view tabs
  2. Choose "Board" layout
  3. Rename the tab to the view name below
  4. Click the filter bar and paste the filter string
  5. Click save
  6. To create the next view, click the tab dropdown → Duplicate view, then repeat from step 3

  View            Filter
  ----            ------
  Engineer        status:eng:po:triage,eng:po:backlog,eng:po:ready,eng:arch:design,eng:arch:plan,eng:arch:breakdown,eng:arch:in-progress,eng:arch:sign-off,eng:dev:implement,eng:dev:code-review,eng:qe:test-design,eng:qe:verify,eng:lead:design-review,eng:lead:plan-review,eng:lead:breakdown-review,done,error
  Human Gates     status:human:po:design-review,human:po:plan-review,human:po:accept,done,error
  Sentinel        status:snt:gate:merge,done,error
  Chief of Staff  status:cos:exec:todo,cos:exec:in-progress,cos:exec:done,done,error

Step 5: Launch

Start all members:

bm start

Each member launches as a Claude Code instance orchestrated by Ralph, running in its own workspace with its own hats, knowledge, and workflow.

Check status:

bm status

Inspect the team, its members, or configured projects:

bm teams show                    # Full team details: members, projects, config
bm members show engineer-01      # Member details: role, status, knowledge files
bm projects list                 # List configured projects with fork URLs

workzone/
  my-team/                                   # Team directory
    team/                                    # Team repo (control plane)
      members/engineer-01/                    # Member config
      projects/my-project/                   # Project-specific dirs
    engineer-01/                             # Workspace repo (agent CWD)
      team/                                  # Submodule → team repo
      projects/
        my-project/                          # Submodule → project fork
      PROMPT.md                              # Copied from team/members/engineer-01/
      CLAUDE.md                              # Copied from team/members/engineer-01/
      ralph.yml                              # Copied from team/members/engineer-01/
      .claude/agents/                        # Symlinks into team/ submodule paths
      .botminter.workspace                   # Workspace marker file

Shell completions (optional)

Enable tab completions for commands, flags, team names, roles, and more:

# Bash
echo 'eval "$(bm completions bash)"' >> ~/.bashrc

# Zsh
echo 'eval "$(bm completions zsh)"' >> ~/.zshrc

# Fish
bm completions fish > ~/.config/fish/completions/bm.fish

Completions are dynamic — they suggest real values from your configuration (team names, roles, members, profiles, etc.). See the CLI Reference for all supported shells.

Next steps

• Follow Your First Journey to create your first epic, launch your agent, and see the full pipeline in action
• Read The Agentic Workflow to understand the philosophy behind the process
• Read Architecture to understand the profile-based generation model
• Learn about the Coordination Model and pull-based work discovery
• See CLI Reference for all available bm commands