My AI Coding Workflow, v3

Posted on Oct 24 • Originally published at helderberto.com

My AI coding workflow changes every few months, so I give it version numbers. New tools ship, models get better, and steps that needed hand-holding last spring now run on their own.

v1 was plan mode and a hand-written SPEC.md. v2 turned that into TracerKit. This post is v3: every step now lives in helderberto/agent-skills.

The idea of v3 fits in one line: each step that used to be a prompt is now a skill, and each "please remember to" is now a check that fails.

TracerKit worked, but it was a separate tool with its own release cycle. Every tweak to a step meant a change there, a release, and an update in each project. I wanted a simpler way to ship updates and add new skills.

I was already keeping my other skills in agent-skills. Moving the spec flow next to them put everything in one place. Now changing a step or adding a skill is one commit.

The ideas from TracerKit survived: interviews before specs, tracer-bullet tickets, verification before a task counts as done. They live in the same repo as the rest of my skills.

I didn't design v3 from scratch. Most of it comes from two repos, and I took what I think is the best of each.

From Matt Pocock's skills I took the shape of the flow:

From Addy Osmani's agent-skills I took the engineering depth inside each step:

Then I cut each one down to what changes the agent's behavior in my projects, and gave them one namespace: /hb:.

flowchart LR accTitle: The v3 flow accDescr: Plan with triage, grill, to-spec and to-tickets. Build with build and review. Ship with to-pr and retro. Small fixes skip from triage straight to build. subgraph Plan direction TB triage --> grill --> spec[to-spec] --> tickets[to-tickets] end subgraph Build direction TB build --> review end subgraph Ship direction TB pr[to-pr] --> retro end Plan --> Build --> Ship Not every task needs all of them. /hb:triage sizes the work and names where to start. A small fix goes straight to /hb:build.

I no longer write the prompts from v1. I wrote them once, as skills, and now I refine the skills. I made the case for this in Skills Are the New CLI.

Take the same dark mode toggle. In v1, I opened plan mode and wrote a paragraph asking Claude to discuss the approach and generate a spec. Now it starts with one command:

/hb:grill dark mode Enter fullscreen mode Exit fullscreen mode The grill interviews me in rounds. Each round asks every question I can answer right now, each with a recommended answer, so a bare "yes" accepts it. Settled terms go to a glossary, and hard-to-reverse decisions become ADRs as they land.

Then the conversation becomes artifacts:

/hb:to-spec dark-mode /hb:to-tickets dark-mode Enter fullscreen mode Exit fullscreen mode The spec lands in.specs/specs/dark-mode.md. The tickets are thin vertical slices with blocking edges, so the agent knows which one is unblocked next. The v1 checklist is still there, but now it has an order.

/hb:build dark-mode Enter fullscreen mode Exit fullscreen mode It takes the next unblocked ticket, works test-first, runs the project's checks and commits. With --all, it fans tickets out to parallel subagents after one approval.

Two commands close it out. /hb:review sends the diff to several reviewers and merges their findings into one ranked verdict. /hb:to-pr runs the checks, pushes, opens the PR and watches CI.

Instructions in a prompt get skipped under pressure. A check that fails does not. So most of my guardrails are things that exit with an error:

The agent can be fast because it can't quietly skip these. I wrote more about why this matters in Code Got Cheap. Review Didn't.

/hb:debug has one rule I now follow without an agent too: no theory before a feedback loop.

Before reading code to guess a cause, the agent has to show one command that reproduces the bug. It must fail on the exact symptom, give the same result every run, and finish in seconds. A failing test, a curl, a headless browser script.

Only then does it list 3 to 5 ranked hypotheses, each with a prediction that could prove it wrong. That stops the agent from fixing the first plausible cause, which is the habit that wasted most of my debugging sessions.

flowchart TD accTitle: The debug loop accDescr: Build a feedback loop that fails, reproduce and minimize, list ranked hypotheses, test each one against the loop until it goes green, then fix and keep the loop as a regression test. loop[Failing loop] --> repro[Reproduce + minimize] --> hyp[3-5 ranked hypotheses] hyp --> test{Loop goes green?} test -- no, next hypothesis --> hyp test -- yes --> fix[Fix + regression test] The flow improves itself The last step is /hb:retro. It reads the session and suggests changes to the environment, not the code: a missing check, a rule in AGENTS.md that should be a lint rule, a file the agent took too long to find.

This is where moving off TracerKit pays off. A retro finding becomes a one-line edit in agent-skills, and every project picks it up on the next update.

The spec is still at the center, as it was in v1. What changed is everything around it. The prompts I kept retyping are skills, and the reminders I kept giving are checks.

This flow will change again with the next tool or model. When it does, it will be a commit to agent-skills, and v4.