Buck Workflow is the AI-assisted development workflow I built after spending a lot of time inside GSD. I wanted to keep the durable planning and agent-searchable context, but make the process flexible enough to match the work instead of forcing every task through the same ceremony.
This isn't a demo. This is the actual workflow behind how I build software with AI agents day to day. I built it for myself because I wanted a version that worked the way I think and build. If it works for other people too, great.
How I Work
a practical loop
These stages are built to work together, but they can work independently too. In most cases, you don't need a prerequisite before you start; the workflow will fill in the missing context for you. The trade-off is detail and control: the more of the loop you use, the more explicit the plan, artifacts, and review surface become. A quick /b-build can stand on its own; a longer loop gives you more structure because you wanted more structure, not because the workflow demanded permission to continue.
01
Explore & Plan
/b-explore, /b-research, /b-plan — map the codebase, gather context, and produce a bounded implementation plan.
02
Build
/b-build or /b-build-hard — implement the smallest safe change, or work through complex/risky changes with more scaffolding.
03
Review
/b-review — check correctness, edge cases, and regressions before it ships; flags docs impact for /b-docs.
04
Save & Commit
/b-save, /b-commit — write durable session memory, update the backlog, and commit with a Conventional Commits message.
You never run the whole loop — you run the part your work needs. Find the sentence that sounds like your situation, follow its line, and each stop tells you why it's there and what it leaves behind.
Every arrow is a habit, not a rule — start in the middle, finish early. Dashed stops are the ones most changes skip.
Quick fix
“It's a small, obvious change — a typo, a copy tweak, a one-line fix.”
/b-build
Skip the ceremony, not the safety net.
Makes the change with the same red-green discipline as any other build.
leaves behind the fix + build trail
/b-review
Even obvious changes get a second pair of eyes.
Checks the fix against the behavior you described, nothing more.
leaves behind a completion matrix
/b-save
This is the step that makes the work findable later.
Writes what happened into memory and the backlog.
leaves behind .context/memory + backlog
/b-commit
One completed unit, one commit.
Writes the commit message from what actually changed.
leaves behind a conventional commit
You end up with: A working fix, a recorded session, and a commit — in minutes, not a meeting.
Half-formed idea
“You can almost say what you want — but not quite.”
/b-brainstorm
Thinking stays loose until it's ready to be concrete.
Interviews you one question at a time into a rough draft.
leaves behind subject folder + draft
/b-plan
A rough draft isn't buildable yet.
Turns the draft into a bounded plan: scope, files, steps, risks.
leaves behind .context/<subject>/plan-*.md
/b-build
Now the agent executes instead of deciding.
Implements the plan with tests, picking up where any earlier session stopped.
leaves behind working code
/b-review
Catch the gap between what you meant and what got built.
Reviews the code against the plan, issue by issue.
leaves behind a completion matrix
/b-save
Close the loop: intent becomes record.
Checkpoints the session into durable memory.
leaves behind .context/memory + backlog
/b-commit
The work leaves the chat and enters git history.
Commits with a message written from the actual change.
leaves behind a conventional commit
You end up with: A real, shipped feature — and a paper trail from first sketch to commit.
Planned feature
“You know exactly what to build.”
/b-plan
Writing it down first shuts the debate up before code starts.
Produces a durable plan on disk — scope, affected files, steps, risks.
leaves behind .context/<subject>/plan-*.md
/b-build
The build step executes a plan that's already pinned down.
Implements it with tests, leaving a resumable trail.
leaves behind working code
/b-review
Verify against the plan, not vibes.
Produces a completion matrix backed by direct evidence.
leaves behind a completion matrix
/b-save
The session outlives the chat window.
Writes memory, updates the backlog, stitches cross-references.
leaves behind .context/memory + backlog
/b-commit
Checkpoint the durable state.
Commits, picking up the draft the save step left.
leaves behind a conventional commit
You end up with: The feature, built against a plan you already argued with and approved.
Unfamiliar code
“You've never touched this part of the codebase.”
/b-explore
You can't plan against code you don't understand.
Maps call chains, data flow, and module boundaries — strictly read-only.
leaves behind research-*.md in .context/
/b-plan
Now the plan sits on facts, not guesses.
Bounded plan against the real architecture.
leaves behind .context/<subject>/plan-*.md
/b-build
Implement with the map in hand.
Executes the plan with tests.
leaves behind working code
/b-review
Blast radius was the risk; check it.
Verifies nothing outside the plan moved.
leaves behind a completion matrix
/b-save
The map you just paid for shouldn't evaporate.
Records what was learned about this part of the codebase.
leaves behind .context/memory + backlog
/b-commit
Ship it.
Conventional commit from the staged change.
leaves behind a conventional commit
You end up with: The change you needed — made without breaking your mental model of the code, because now you have one.
Hard bug
“It's broken and nobody knows why.”
/b-diagnose
No fix until the symptom actually reproduces. No guessing.
Builds a red test first, then hunts the cause through it.
leaves behind repro + diagnosis record
/b-iterate
Once the cause is known, the fix is small and well-defined.
Applies the fix with the regression test in place.
leaves behind the fix
/b-review
Prove the bug is dead and nothing else moved.
Checks the fix and the regression test together.
leaves behind a completion matrix
/b-save
The diagnosis is knowledge — record it.
Writes the defect and its cause into memory.
leaves behind .context/memory + backlog
/b-commit
Fix and test land together.
Commits the whole unit.
leaves behind a conventional commit
You end up with: A reproduced, regression-tested fix — and a written-down defect instead of a war story.
Big or risky change
“This is too big for one session — migrations plus API plus UI.”
/b-plan
Big work needs a plan you can put down and pick back up.
Produces the full plan on disk.
leaves behind .context/<subject>/plan-*.md
/b-phase
One giant context window is where big plans die.
Splits the plan into phases that ship and review alone.
leaves behind plan-*-phases.md + phase-N files
/b-build
Risky work gets the heavier scaffolding (build-hard mode).
Runs the build loop per phase with extra verification; each phase is resumable.
leaves behind phase code, one phase at a time
/b-review
Every phase gets the same correctness gate.
Reviews each phase against its slice of the plan.
leaves behind per-phase completion matrices
/b-save
Between phases is exactly when context runs out.
Checkpoints after each phase so the next one starts clean.
leaves behind .context/memory + backlog
/b-commit
One completed phase, one commit.
Commits each phase separately.
leaves behind a commit per phase
You end up with: The whole change, shipped phase by phase — each one reviewed and committed on its own.
The words
six terms, no jargon left
Skill
A packaged ability your agent can load — instructions plus, sometimes, its own scripts. This whole workflow is made of them.
Slash command
The /b-* name you type to invoke a skill. One command, one kind of thinking.
Harness
The AI coding tool you run — Pi, Claude Code, Cursor, ZCode. The same skills install into any of them.
Plan
A markdown file in .context/ that says what will change and why — written before code, so it can be argued with.
Session record
What happened while you worked, written to memory as you go. It's how a task survives a closed laptop.
Guardrail
An automatic check — tests, coverage, complexity — the work must pass before it's called done. It measures; it never edits.
Install
copy this into your agent
Install the buck-workflow skills using the instructions here:
https://github.com/evilbuck/buck-workflow-pi/blob/master/agent-install_instructions.md
This gives your agent the GitHub-hosted install document directly.
Philosophy
one principle
The goal is to keep intent attached to the code without taking judgment away from the engineer. Buck Workflow separates plan from session record, which reduces guessing later and leaves a more durable trail behind each change. It's not prescriptive: skip stages, start in the middle, or work ad hoc. A fast /b-build → /b-save is fine when the change is small; the full brainstorm → plan → research → build → save loop is there when it isn't.
Runs Everywhere
one shared skill layer
A multi-harness installer detects what's on your machine and wires the same skills into each one. Originally built in OpenCode, later adapted to Pi, and now running in Oh My Pi, it stays useful because it is agent-agnostic rather than locked to a single harness.
Each command is one named entrypoint for one kind of thinking. You don't have to run them all — pick the ones the work needs, or skip straight to a fast /b-build → /b-save when the change is small.
01
Discover
Gather context — local or external — before committing to a direction.
/b-brainstorm
Captures a half-formed idea as a loose first draft before it's ready for a real plan. It interviews you one question at a time.
Use it when you know the direction but not the shape — "add OAuth" with no details yet.
/b-explore
Maps your own codebase — call chains, data flow, module boundaries — without changing anything.
Use it before planning unfamiliar code, or to gauge blast radius before a refactor.
/b-research
Investigates the outside world: library APIs, docs, best practices, and competing approaches.
Use it when the answer lives outside your repo — picking a provider, checking a framework's API.
/b-grill
Stress-tests a plan or design through relentless structured questioning, walking every branch of the decision tree.
Use it when a plan feels clever but unproven — it surfaces hidden assumptions and flags when a plan is big enough to phase.
/b-diagnose
A tight, red-capable feedback loop for hard bugs and performance regressions — refuses to hypothesize about a fix until a command actually reproduces the reported symptom.
Use it when something is broken, throwing, or slow and nobody knows why yet; it hands off to /b-iterate or /b-build once the cause is confirmed and a regression test is in place.
02
Plan
Turn gathered context into a bounded, reviewable path to the change.
/b-plan
Turns gathered context into a bounded implementation plan: scope, affected files, steps, risks, and verification.
Use it once you know what you want and need the path to it.
/b-phase
Splits a large plan into sequential, independently-verifiable phases with dependencies and difficulty hints.
Use it when a plan is too big for one session — migrations plus API plus UI — so each phase ships and reviews on its own.
/b-present
Renders .context/ artifacts into a shareable async-readable site — an overview page plus optional detail pages.
Use it to brief a teammate or stakeholder without making them read every plan file.
03
Build
Write the code, leaving a durable trail behind it.
/b-build
Implements well-defined work with TDD — red, green, refactor. /b-build-hard runs the same loop with more scaffolding for complex or risky changes.
Use it for the actual code; pick hard when the trade-offs matter.
/b-iterate
Small follow-up fixes after review — a rename, a lint cleanup, one flagged issue.
Use it for the tiny stuff; it escalates to /b-build if the work spreads.
04
Close
Check the work, sync the docs, and turn the session into durable record.
/b-review
Reviews the implementation against the plan and produces a completion matrix backed by direct evidence, not vibes. Classifies every issue as in-plan or out-of-plan.
Use it as the correctness gate before anything ships.
/b-docs
Syncs the project's living docs — domain language, architecture decisions, conventions — with what was actually built.
Use it when review flags that a decision or convention changed and should be recorded.
/b-save
Checkpoints the session into durable memory, the index, and the backlog. Turns intent (plans) into record (history).
Use it at every natural stop — it's the step that makes work survive a closed chat or context compaction.
/b-commit
Writes a Conventional Commits message from staged changes and commits, picking up the draft /b-save left if there is one.
Use it to checkpoint durable state at the end of a loop.
Behind Each Command
the reasoning behind each one
The card above says what each command does. This section is for why — what each one earns its place for, the way I actually reach for it, and what changes when I skip it.
/b-brainstormDiscover
Talk it through before you know exactly what you want to build./b-brainstorm is for the stage where the idea is still loose and you want a real back-and-forth with the agent to help flesh it out. Sometimes that means clarifying what you already have in mind; sometimes it means discovering a better shape for the idea while you're talking.
It is not locked to the start of the workflow. You can begin with a brainstorm, move into a plan, then brainstorm again once you see the plan more clearly. Or you can do one brainstorm and go straight into /b-build. The point is not to follow a ritual. The point is to have a place where thinking stays loose until you're ready to make it concrete.
When I reach for it.
When I do not know exactly what I want yet and I want the agent to think with me instead of prematurely turning the idea into a plan. How often I use it depends on how much detail and control I want. There are no rules.
/b-exploreDiscover
Figure out what the local codebase actually does before you touch it./b-explore is the internal investigation step. It is not for web research; it is for tracing unfamiliar local code, mapping architecture, following data flow, and figuring out what a project is doing before you try to plan against it.
This is the one I reach for when I need to refresh my memory on a project or when I do not know enough about the local code to trust my assumptions yet. It stays read-only, writes findings into .context/, and is especially useful in a sub-agent because it keeps the exploration work from bloating the main session context.
When I reach for it.
When I do not know how a project works, what a subsystem does, or where something lives yet. It is the local file and architecture pass I do before planning, or anytime I need to re-orient myself without changing code.
/b-researchDiscover
Go gather what you do not know yet.
I tend to use /b-research after a brainstorm or a plan, when I know the shape of the question but I do not know enough to make the decision yet. It pulls from my Obsidian notes, the web, and places I already trust to look for real opinions and implementation detail.
This is the step for closing knowledge gaps. Which library should I use? Which tool fits this problem better? What does the API actually look like in practice? /b-research is there for the moments where moving forward without more context would just mean guessing with confidence.
When I reach for it.
Usually after /b-brainstorm or /b-plan, but it can come first too. Like the rest of the tools, it is not limited to one place in the process. I use it whenever the next decision depends on information I do not have yet.
/b-grillDiscover
Stress-test the idea before you hand it off./b-grill came out of Matt Pocock's grill-me idea, but with some limits added because a full grilling session can get exhausting fast. This version usually aims for around 20 questions. It can go over, but that threshold is where it starts thinking about whether the work is big enough to phase.
You can use it anywhere: hand it a plan, a brainstorm, a file, or just raw context and let it start pushing on the edges. When you use it inside Buck Workflow, it keeps updating the same subject files, memory, and surrounding artifacts rather than spinning off into a separate track. Its job is to really flesh something out before you move into /b-plan or /b-build. It is incredibly useful, but also tedious if you use it for everything, which is why it is tuned to stop short of becoming the whole workflow.
When I reach for it.
When I want pressure on an idea before I commit to it. Sometimes that means the full session; sometimes it means telling it to stop at five questions, then reevaluating. Like the rest of the tools, it is available anywhere in the process — the question is how much stress-testing the idea actually needs.
/b-planPlan
Putting pen to paper without picking up a hammer.
I use /b-plan when I have a pretty good idea of what I want to build and I need something durable to review and ask questions against — before any code changes. The plan goes to disk inside .context/, not into the codebase. Nothing is built yet, so nothing has to be undone yet.
What it gives me is a thing to argue with. I draft the plan, the agent helps me tighten it without padding it with extras, and I iterate on the same file until the shape feels right. Once it's on paper, the next move is locked — and that's the point. Writing the plan first is what shuts the agent up about starting to build. /b-build can then stay about the build, not about deciding what to build.
It also hands off cleanly. A future session — mine, days later, when the chat is gone — opens .context/<subject>/plan-*.md and picks up the version of the idea that already survived review. The agent that runs /b-build isn't re-deriving the work; it's executing a plan that was already pinned down.
When I reach for it.
When the picture is clear enough to write down, but the work is big enough that writing it down earns its keep — multi-step, multi-file, or anything I'd want to resume. For a one-line tweak, the loop stays /b-build → /b-save; planning would be ceremony.
/b-phasePlan
Break a plan down when the plan is too big to carry whole.
During planning, the workflow looks at how large the plan actually is. If it is too large, it will suggest phasing it. That is where /b-phase comes in: its job is to take a set of work and organize it into phases that belong together instead of trying to force everything through one oversized session.
The point is to keep the context slim for each piece of work. Each phase becomes a smaller, more atomic set of changes that can be executed, reviewed, and resumed without dragging the rest of the project into the same context window. It is not just about making a long plan prettier; it is about making the work practical to do.
When I reach for it.
When /b-plan shows me the work is too broad to carry as one unit. If a task naturally breaks into pieces that should travel together, /b-phase is how I group them so each phase stays coherent and atomic.
/b-buildBuild
The build step — with or without a plan ahead of it./b-build works two ways. If there's already a plan — or any durable artifact from /b-plan, /b-research, /b-explore, or /b-brainstorm — it picks those up and runs against them. If there isn't, it generates a quick plan of its own before it writes a line of code. Either way, it leaves a trail: the plan, the todos, the progress, all as durable artifacts sitting in .context/.
That trail is what makes the build resumable. Stop mid-feature, close the laptop, open it tomorrow on a different machine or in the cloud — the next /b-build sees where the last one left off. The work survives context loss, chat compaction, and the gap between sessions.
/b-build works ad‑hoc or as part of the entire buck workflow. The durable artifacts are what make either path usable: when you start, you pick up where the last session left off; when you stop, the next session starts from the same place.
When I reach for it.
Every time I'm about to write code — whether I'm opening a fresh session on a small change or continuing a plan I already have. Ad hoc, or as part of the full loop. The durable trail is what makes the difference between work that survives a closed chat and work that doesn't.
{Open source, MIT licensed, and actively maintained. PRs for new harness support are welcome.}
View on GitHub →