How to Actually Use Buildmate (The Practical Guide)

Source: Dev.to

So You Installed It, Now What?

Maybe you read my first post about Buildmate, or you just stumbled on the GitHub repo and thought, “Cool, I’ll try it.” Either way—you’ve got it installed, but now you’re staring at your terminal wondering, “…what do I actually do with this thing?”

Docs are great, but sometimes you just want someone to show you how they actually use the tool. This is that. Real workflows. Real commands. Stuff I do every day.

Let’s go.

Quick Setup (In Case You Skipped It)

If you already did this, skip ahead. If not:

git clone https://github.com/vadim7j7/buildmate.git
cd buildmate
python3 -m venv .venv && .venv/bin/pip install -e .

Then bootstrap your project:

# Pick your stack
buildmate rails /path/to/my-app
buildmate nextjs /path/to/my-app --ui=tailwind
buildmate rails+nextjs /path/to/my-app

# Or just use a preset
buildmate --profile saas /path/to/my-app

Not sure what stacks are available? Check with:

buildmate --list           # all stacks
buildmate --profiles       # preset combos
buildmate --options nextjs # options for a stack

After this you’ll have a .claude/ folder with all the agent stuff. That’s it—you’re ready.

Your First /pm Command

/pm is the main command. PM stands for Project Manager. It kicks off the whole workflow—planning, building, testing, reviewing, everything.

1. Open your project and run claude.
2. Type:

/pm Build a user profile page with avatar, bio, and edit functionality

Phase 1 – Planning (interactive)

PM: Ok so for user profile, I'm thinking:

    Requirements:
    - Profile page showing avatar, name, bio
    - Edit mode to update info
    - Avatar upload (or URL?)
    - Save/cancel buttons

    Questions:
    - Should avatar be file upload or just URL input?
    - Where does this page live? /profile? /settings?
    - Need to create User model or exists already?

You: URL is fine for now. /profile route. User model exists.

PM: Cool, here's the plan:
    [shows feature file with all the details]

    Ready to build?

You: yep go

Phases 2‑5 – Automatic

From here the agents take over:

[Phase 2: Implementation]
→ Spawning backend‑developer...
→ Creating ProfileController
→ Adding routes
→ Spawning frontend‑developer...
→ Creating ProfilePage component
→ Creating EditProfileForm component

[Phase 3: Testing]
→ Spawning testers...
→ Writing controller specs
→ Writing component tests
→ Running quality gates...
→ Grind agent fixing 2 lint errors...

[Phase 4: Review]
→ Spawning reviewers...
→ Backend review: APPROVED
→ Frontend review: APPROVED

[Phase 5: Verification]
→ Starting dev server...
→ Testing /profile route...
→ Component renders ✓
→ Form submits ✓

Done! Score: 0.89 (B+)

You now have a working profile page—complete with tests, reviews, and verification.

Note: It feels like magic, but it’s just a set of specialized agents working in order. Backend dev writes the backend, frontend dev writes the UI, testers write tests, etc.

The Agents (Who Does What?)

The agents live in .claude/agents/ as markdown files. Feel free to read or edit them—more on that later.

Commands You’ll Actually Use

/pm "task"

The big one. Triggers the full workflow.

/pm Add pagination to the products list
/pm Fix the login bug where sessions expire too fast
/pm Build checkout flow with Stripe integration

Use it for any substantial work: new features, big fixes, new pages, etc.

/verify

Runs your code to test it. This is newer and I use it all the time.

/verify                              # test last changes
/verify --component Navbar           # test a specific component
/verify --endpoint POST /api/users   # test a specific endpoint
/verify --page /dashboard            # test a whole page

If something fails, the system tries to fix it automatically (up to three attempts).

/new-model and /new-component

Quick scaffolding that creates the thing plus tests and boilerplate.

/new-model Product name:string price:decimal active:boolean
/new-component ProductCard
/new-component forms/CheckoutForm

It follows your project conventions, saving you a lot of manual work.

/parallel

Got independent tasks? Run them simultaneously.

/parallel "Add user avatars" "Add product images" "Add company logos"

Overview

Use separate Git worktrees, run agents in each, and merge when done. This is handy when you have a bunch of similar tasks.

/security

Security audit – run it before you deploy, please.

/security

Checks for injection, auth issues, XSS, CSRF, and other OWASP concerns.

/eval

Want a quick score without the full workflow?

/eval

Returns a grade – useful for checking your own work.

/test and /review

Run only what you need:

/test          # just run tests
/review        # just review current changes

Git Workflow (The /branch → /ship Flow)

Instead of manually creating branches, writing commit messages, pushing, and drafting PR descriptions at 5 pm when your brain is fried, just:

/branch user-auth          # creates feature/user-auth
# … do your work or use /pm …
/ship                      # commits, pushes, creates PR

• Auto‑generates commit messages from your changes.
• Writes the PR description for you.
• Runs quality gates before shipping.

More examples

/branch login-fix --type fix          # creates fix/login-fix
/branch user-auth --issue 42          # links to GitHub issue #42
/sync                                 # rebase on main if you’re behind
/ship --draft                         # create PR as draft

Syncing

/sync                    # rebase on main
/sync --merge            # merge instead of rebase
/sync --base develop     # sync with develop branch

Shipping

/ship                    # commit + push + create PR
/ship --draft            # same but draft PR
/ship --no-pr            # just commit and push, no PR

No more “oh wait I forgot to push.” No more staring at the PR template trying to remember what you changed – the commands handle it all.

Customizing Your Setup

Editing Agents

Agents are plain markdown files. Edit them to suit your workflow.

.claude/agents/
├── orchestrator.md          # the PM brain
├── backend-developer.md    # Rails/FastAPI dev
├── frontend-developer.md
├── grind.md
└── …

Open any file to see instructions, patterns, dos and don’ts. Change whatever you want.

Example: Force the backend developer to always use a specific gem.

# backend-developer.md (excerpt)

## Preferred gems
- my-special-gem (>= 2.0)

Feel free to tailor each agent’s behavior to match your team’s conventions.

Rules

• Always use Pagy for pagination (not Kaminari)
• Always use Pundit for authorization
• …

Adding Patterns

Got coding patterns you always follow? Add them to .claude/patterns/.
These are reference docs the agents read—e.g., “how we structure services” or “our API response format”.

Changing Quality Gates

In the stack config you can change what commands run:

quality_gates:
  lint:
    command: bundle exec rubocop
    fix_command: bundle exec rubocop -A
  tests:
    command: bundle exec rspec

Add more, remove some, or change commands—whatever works for your project.

Real Workflows I Actually Use

Building a New Feature

This is the flow for ~80 % of my work:

1. /pm Build [feature description]
2. Answer a few questions about requirements
3. Approve the plan
4. Go get coffee
5. Come back – it’s done
6. Maybe tweak something small manually
7. Commit and push

Most features now take 10‑15 minutes instead of half a day.

Fixing a Bug

1. /pm Fix [describe the bug and where it is]
2. Agent reads the code, finds the issue
3. Fixes it
4. Writes a test so it doesn’t happen again
5. Done

For tiny bugs I sometimes fix them myself because it’s faster, but for anything tricky I let the agent handle it.

Adding to Existing Code

1. /pm Add [thing] to [existing feature]
2. Agent reads the existing code first
3. Follows the patterns already there
4. Adds the new thing in the same style

The agent reads your code and matches the style, so you don’t get “this new code looks totally different from everything else.”

Quick Scaffolding Day

When I’m setting up a new project I fire off a bunch of commands:

/new-model User email:string name:string
/new-model Product title:string price:decimal
/new-model Order user:references total:decimal
/new-component Navbar
/new-component Footer
/new-component ProductCard
...

Boom—everything is scaffolded (including tests) in about five minutes.

Common Issues (And How to Fix Them)

Tips From Actually Using This Thing

• Be specific in your prompts. “Build a login page” is okay; “Build a login page with email/password, remember‑me checkbox, forgot‑password link, and redirect to dashboard after login” is better.
• Answer the planning questions. Don’t just say “whatever.” More context → better output.
• Use /verify often. Catches dumb mistakes before you even see them.
• Read the feature files. They live in .claude/context/features/ and are great for remembering what was built and why.
• Edit the agents. Seriously—make them yours. Add your patterns, rules, and preferences.
• Trust but verify. The code is usually good, but always give it a quick look before shipping.
• Use the git flow. /branch → do work → /ship. No more manual PR descriptions at 5 pm.

What’s Next

I’m working on a website‑cloning tool: point it at any site and it will generate your own version using your UI library. That’ll be a whole other post.

For now, go try this stuff. Break things. Fix things. Let me know what works and what doesn’t.

GitHub:

Found This Useful?

If this saved you some time, maybe buy me a coffee?

☕ Buy Me A Coffee

Now go build something cool.

— Vadim