because "just read the docs" isn't helpful and we both know it
So You Installed It, Now What?
Ok so maybe you read my first post about Buildmate. Or maybe you just found the GitHub and thought "cool I'll try it." Either way - you got it installed but now you're staring at your terminal like "...what do I actually do with this thing?"
Yeah I get it. Docs are great and all but sometimes you just want someone to show you how they actually use the thing. So thats what this is. Real workflows. Real commands. Stuff I actually do every day.
Lets 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 got a .claude/ folder with all the agent stuff. Thats it. Your ready.
Your First /pm Command
Ok so /pm is the main thing. PM stands for Project Manager. Its the command that kicks off the whole workflow - planning, building, testing, reviewing, everything.
Lets try it. Open your project and run claude, then type:
/pm Build a user profile page with avatar, bio, and edit functionality
Heres what happens:
Phase 1 - Planning (this part is 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, heres the plan:
[shows feature file with all the details]
Ready to build?
You: yep go
Phases 2-5 (automatic from here)
Now it just runs. You dont do anything.
[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+)
And now you have a working profile page. With tests. Reviewed. Verified.
I know it sounds like magic but its not really. Its just agents doing their specific jobs in order. Backend dev writes backend. Frontend dev writes frontend. Tester writes tests. Each one is focused on one thing.
The Agents (Who Does What)
Quick reference cause I always forget:
They live in .claude/agents/ as markdown files. You can read them if your curious. Or edit them - more on that later.
Commands You'll Actually Use
/pm "task"
The big one. 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 this for anything substantial. Features, big fixes, new pages.
/verify
Tests your code by actually running it. This ones newer and honestly I use it all the time now.
/verify # test last changes
/verify --component Navbar # test specific component
/verify --endpoint POST /api/users # test specific endpoint
/verify --page /dashboard # test whole page
If something fails it tries to fix it automatically. Up to 3 times.
/new-model and /new-component
Quick scaffolding. Creates the thing plus tests plus all the boilerplate.
/new-model Product name:string price:decimal active:boolean
/new-component ProductCard
/new-component forms/CheckoutForm
Way faster than doing it manually. Follows your project conventions too.
/parallel
Got independent tasks? Run them at the same time.
/parallel "Add user avatars" "Add product images" "Add company logos"
Creates separate git worktrees, runs agents in each, merges when done. I use this when I got a bunch of similar things to do.
/security
Security audit. Run it before you deploy pls.
/security
Checks for injection, auth issues, XSS, CSRF, all that OWASP stuff.
/eval
Just want a score without the whole workflow?
/eval
Gives you the grade. Good for checking your own work.
/test and /review
Sometimes you just want one thing:
/test # just run tests
/review # just review current changes
Git Workflow (The /branch → /ship Flow)
Ok so this one is newer and I use it all the time now.
Instead of manually creating branches, writing commit messages, pushing, writing PR descriptions at 5pm when your brain is fried... just:
/branch user-auth # creates feature/user-auth
# ... do your work or use /pm ...
/ship # commits, pushes, creates PR
Thats it. It auto-generates commit messages from your changes. Writes the PR description for you. Even 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 What Happens When B2B Buyers Start Using ChatGPT?
/sync # rebase on main if youre behind
/ship --draft # create PR as draft
The /sync one is useful when main has moved ahead and you need to catch up. It handles the rebase (or merge if you prefer) and force-pushes for you.
/sync # rebase on main
/sync --merge # merge instead of rebase
/sync --base develop # sync with develop branch
And /ship does everything at once:
/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. It just does it.
Customizing Your Setup
Editing Agents
The agents are just markdown files. You can edit them.
.claude/agents/
├── orchestrator.md # the PM brain
├── backend-developer.md # Rails/FastAPI dev
├── frontend-developer.md
├── grind.md
└── ...
Open one up. Youll see instructions, patterns, do's and donts. Change whatever you want.
For example maybe you want the backend dev to always use a specific gem:
## Rules
- Always use Pagy for pagination (not Kaminari)
- Always use Pundit for authorization
- ...
Just add it to the file. Next time it runs itll follow your rules.
Adding Patterns
Got coding patterns you always follow? Add them to .claude/patterns/.
These are reference docs the agents read. Stuff like "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, change commands. Whatever works for your project.
Real Workflows I Actually Use
Building a New Feature
This is like 80% of what I do:
1. /pm Build [feature description]
2. Answer a few questions about requirements
3. Approve the plan
4. Go get coffee
5. Come back, its done
6. Maybe tweak something small manually
7. Commit and push
Thats it. Most features take 10-15 minutes now 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 doesnt happen again
5. Done
For small bugs I sometimes just do it myself cause its faster. But for anything tricky I let the agent figure it out.
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
This is where it really shines tbh. It actually reads your code and matches the style. No more "this new code looks totally different from everything else."
Quick Scaffolding Day
When I'm setting up a new project I'll just rapid fire:
/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. All the basics in like 5 minutes. With tests.
Common Issues (And How to Fix Them)
"Its stuck in a loop"
The grind agent will try 10 times then give up. If its not converging theres probably something weird going on. Read the error, might need manual fix.
"Agent didnt follow my style"
Edit the agent file in .claude/agents/. Add specific rules about your style. Be explicit - "always use X, never use Y."
"Tests keep failing"
Check if your test setup is correct. Sometimes the agent writes good tests but the test environment isnt configured right. Run the tests manually to see whats up.
"It made too many files"
Yeah it can get enthusiastic sometimes. You can tell it in the initial prompt: "keep it simple, minimal files."
"The code works but I dont like how its structured"
Use /review to get feedback, or just refactor yourself. The agents are good but theyre not perfect. Your judgment still matters.
Tips From Actually Using This Thing
Whats Next
Working on website cloning - point it at any site and itll generate your own version using your UI library. Thats gonna be a whole other post tho.
For now, go try this stuff. Break things. Fix things. Let me know what works and what doesnt.
GitHub: github.com/vadim7j7/buildmate
Found This Useful?
If this saved you some time maybe buy me a coffee?
☕ Buy Me A Coffee
Now go build something cool.
- Vadim
More...
So You Installed It, Now What?
Ok so maybe you read my first post about Buildmate. Or maybe you just found the GitHub and thought "cool I'll try it." Either way - you got it installed but now you're staring at your terminal like "...what do I actually do with this thing?"
Yeah I get it. Docs are great and all but sometimes you just want someone to show you how they actually use the thing. So thats what this is. Real workflows. Real commands. Stuff I actually do every day.
Lets 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 got a .claude/ folder with all the agent stuff. Thats it. Your ready.
Your First /pm Command
Ok so /pm is the main thing. PM stands for Project Manager. Its the command that kicks off the whole workflow - planning, building, testing, reviewing, everything.
Lets try it. Open your project and run claude, then type:
/pm Build a user profile page with avatar, bio, and edit functionality
Heres what happens:
Phase 1 - Planning (this part is 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, heres the plan:
[shows feature file with all the details]
Ready to build?
You: yep go
Phases 2-5 (automatic from here)
Now it just runs. You dont do anything.
[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+)
And now you have a working profile page. With tests. Reviewed. Verified.
I know it sounds like magic but its not really. Its just agents doing their specific jobs in order. Backend dev writes backend. Frontend dev writes frontend. Tester writes tests. Each one is focused on one thing.
The Agents (Who Does What)
Quick reference cause I always forget:
| PM/Orchestrator | Plans the work, coordinates everyone | First, stays in control |
| Backend Developer | Writes Rails/FastAPI code | Phase 2 |
| Frontend Developer | Writes React/Next.js code | Phase 2 |
| Backend Tester | Writes backend tests | Phase 3 |
| Frontend Tester | Writes frontend tests | Phase 3 |
| Grind | Runs linters in loop, fixes errors | Phase 3 |
| Verifier | Actually runs the code to test it | Phase 3-4 |
| Reviewers | Code review | Phase 4 |
| Eval | Scores the code | Phase 5 |
| Security Auditor | Checks for vulnerabilities | When you ask |
They live in .claude/agents/ as markdown files. You can read them if your curious. Or edit them - more on that later.
Commands You'll Actually Use
/pm "task"
The big one. 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 this for anything substantial. Features, big fixes, new pages.
/verify
Tests your code by actually running it. This ones newer and honestly I use it all the time now.
/verify # test last changes
/verify --component Navbar # test specific component
/verify --endpoint POST /api/users # test specific endpoint
/verify --page /dashboard # test whole page
If something fails it tries to fix it automatically. Up to 3 times.
/new-model and /new-component
Quick scaffolding. Creates the thing plus tests plus all the boilerplate.
/new-model Product name:string price:decimal active:boolean
/new-component ProductCard
/new-component forms/CheckoutForm
Way faster than doing it manually. Follows your project conventions too.
/parallel
Got independent tasks? Run them at the same time.
/parallel "Add user avatars" "Add product images" "Add company logos"
Creates separate git worktrees, runs agents in each, merges when done. I use this when I got a bunch of similar things to do.
/security
Security audit. Run it before you deploy pls.
/security
Checks for injection, auth issues, XSS, CSRF, all that OWASP stuff.
/eval
Just want a score without the whole workflow?
/eval
Gives you the grade. Good for checking your own work.
/test and /review
Sometimes you just want one thing:
/test # just run tests
/review # just review current changes
Git Workflow (The /branch → /ship Flow)
Ok so this one is newer and I use it all the time now.
Instead of manually creating branches, writing commit messages, pushing, writing PR descriptions at 5pm when your brain is fried... just:
/branch user-auth # creates feature/user-auth
# ... do your work or use /pm ...
/ship # commits, pushes, creates PR
Thats it. It auto-generates commit messages from your changes. Writes the PR description for you. Even 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 What Happens When B2B Buyers Start Using ChatGPT?
/sync # rebase on main if youre behind
/ship --draft # create PR as draft
The /sync one is useful when main has moved ahead and you need to catch up. It handles the rebase (or merge if you prefer) and force-pushes for you.
/sync # rebase on main
/sync --merge # merge instead of rebase
/sync --base develop # sync with develop branch
And /ship does everything at once:
/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. It just does it.
Customizing Your Setup
Editing Agents
The agents are just markdown files. You can edit them.
.claude/agents/
├── orchestrator.md # the PM brain
├── backend-developer.md # Rails/FastAPI dev
├── frontend-developer.md
├── grind.md
└── ...
Open one up. Youll see instructions, patterns, do's and donts. Change whatever you want.
For example maybe you want the backend dev to always use a specific gem:
## Rules
- Always use Pagy for pagination (not Kaminari)
- Always use Pundit for authorization
- ...
Just add it to the file. Next time it runs itll follow your rules.
Adding Patterns
Got coding patterns you always follow? Add them to .claude/patterns/.
These are reference docs the agents read. Stuff like "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, change commands. Whatever works for your project.
Real Workflows I Actually Use
Building a New Feature
This is like 80% of what I do:
1. /pm Build [feature description]
2. Answer a few questions about requirements
3. Approve the plan
4. Go get coffee
5. Come back, its done
6. Maybe tweak something small manually
7. Commit and push
Thats it. Most features take 10-15 minutes now 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 doesnt happen again
5. Done
For small bugs I sometimes just do it myself cause its faster. But for anything tricky I let the agent figure it out.
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
This is where it really shines tbh. It actually reads your code and matches the style. No more "this new code looks totally different from everything else."
Quick Scaffolding Day
When I'm setting up a new project I'll just rapid fire:
/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. All the basics in like 5 minutes. With tests.
Common Issues (And How to Fix Them)
"Its stuck in a loop"
The grind agent will try 10 times then give up. If its not converging theres probably something weird going on. Read the error, might need manual fix.
"Agent didnt follow my style"
Edit the agent file in .claude/agents/. Add specific rules about your style. Be explicit - "always use X, never use Y."
"Tests keep failing"
Check if your test setup is correct. Sometimes the agent writes good tests but the test environment isnt configured right. Run the tests manually to see whats up.
"It made too many files"
Yeah it can get enthusiastic sometimes. You can tell it in the initial prompt: "keep it simple, minimal files."
"The code works but I dont like how its structured"
Use /review to get feedback, or just refactor yourself. The agents are good but theyre not perfect. Your judgment still matters.
Tips From Actually Using This Thing
- Be specific in your prompts. "Build a login page" is ok. "Build a login page with email/password, remember me checkbox, forgot password link, and redirect to dashboard after" is better.
- Answer the planning questions. Dont just say "whatever." The more context you give, the better the output.
- Use /verify often. Catches dumb mistakes before you even see them.
- Read the feature files. They live in .claude/context/features/. Good for remembering what was built and why.
- Edit the agents. Seriously. Make them yours. Add your patterns, your rules, your preferences.
- Trust but verify. The code is usually good but always do a quick look before shipping.
- Use the git flow. /branch → do work → /ship. No more manual PR descriptions at 5pm.
Whats Next
Working on website cloning - point it at any site and itll generate your own version using your UI library. Thats gonna be a whole other post tho.
For now, go try this stuff. Break things. Fix things. Let me know what works and what doesnt.
GitHub: github.com/vadim7j7/buildmate
Found This Useful?
If this saved you some time maybe buy me a coffee?
☕ Buy Me A Coffee
Now go build something cool.
- Vadim
More...