My AI Coding Workflow, v3

My AI coding workflow evolves every few months, so I assign version numbers to track changes. Version 1 started with plan mode and a hand-written SPEC.md, while version 2 introduced TracerKit. Version 3 of my workflow consolidates all steps into a unified system called helderberto/agent-skills.

Version 3 streamlines the process by converting prompts into skills and "please remember to" commands into checks that fail. This approach simplifies updates and adds new skills, as changes are made through a single commit. The core concepts from TracerKit, such as interviews before specs and verification before task completion, remain intact but are now integrated into the same repository as other skills.

I didn't design version 3 from scratch; instead, I built upon existing repositories. I incorporated the flow structure from Matt Pocock's skills, including grill-me for interviewing and diagnosing-bugs for phased debugging. The engineering depth inside each step was taken from Addy Osmani's agent-skills, focusing on frontend UI engineering, source-driven development, security and hardening, and performance optimization.

The workflow consists of eight main commands: triage, grill, spec, tickets, build, review, pr, and retro. Smaller tasks may skip certain steps and move directly to building. The plan phase includes triage, grill, spec, and tickets. The build phase involves building and reviewing. The ship phase consists of creating pull requests and retrospection.

Each task follows a specific order, with small fixes bypassing some steps. The /hb:triage command sizes the work and names the starting point. For small fixes, the workflow moves straight to /hb:build. The /hb:build command takes the next unblocked ticket, conducts test-first development, runs project checks, and commits changes. The --all option allows parallel execution of tickets after one approval.

The /hb:review command sends the diff to multiple reviewers and merges their findings into a ranked verdict. The /hb:to-pr command runs checks, pushes the code, opens a pull request, and monitors CI. Guardrails are in place to ensure adherence to standards, such as lint, type, and test checks, coverage limits, hitl tickets, secret scanning, and hardening checks.

Debugging is handled through the /hb:debug command, which follows a strict process of reproducing the bug, listing ranked hypotheses, testing each hypothesis against the loop, fixing the issue, and adding a regression test. This approach minimizes the likelihood of fixing the first plausible cause, a common debugging pitfall.

After debugging, the /hb:retro command analyzes the session and suggests improvements to the environment, not the code. This step benefits from moving away from TracerKit, as retro findings can be implemented more efficiently as one-line edits in agent-skills, which are then adopted by all projects during the next update.