hacking-workflow

name	hacking-workflow
description	Use at the START of any non-trivial build or change in a git repo — "let's build X", "hack on X", "start a hacking session", "run the loop", "new project", "implement this". The spine that sequences shaping → planning → build → craft → verify → review → finish, with human-approval gates

Hacking Workflow

Overview

Core principle: Real work runs a loop with gates — points where a human decides and where you must prove progress before advancing. The loop keeps momentum honest: you never drift from a vague idea straight into code, and you never call something done without evidence. This skill is the spine; each phase is its own skill it hands off to.

This is the front door. When a build starts, run the loop. Right-size the ceremony to the work (a spike skips most of it) but never skip a human-approval gate.

Classify First (right-size the loop)

Announce which path you're on. Complexity can only upgrade the path, never downgrade it.

Path	What it is	Loop
Spike	"Can this even be done?" throwaway probe	spike-and-stabilize only, report back. Skip the rest.
Bounded	A clear, contained change	Shape briefly → build → verify → finish. Skip the plan doc.
Architectural	New system, many parts, real design choices	The full loop below.

The Loop

Track the whole thing in beads from the first phase (using-beads) — file the work, close as you go.

Phase 0 — SHAPE       understand the goal, weigh approaches, get buy-in
   → shaping.  GATE: the human approves the intent/design before ANY code.

Phase 1 — ISOLATE     a clean workspace so nothing races or leaks onto main
   → using-worktrees.  GATE: clean baseline (builds/tests green, or human OKs).

Phase 2 — PLAN        (architectural only) map files + right-sized tasks, file as beads
   → planning.  GATE: plan filed; pick execution mode (subagents vs inline).

Phase 3 — BUILD       make it work, thinnest slice first
   → builder (walking-skeleton, spike-and-stabilize). Keeper code is test-first → test-first.

Phase 4 — CRAFT       make it elegant, behavior-preserving
   → whittler.

Phase 5 — VERIFY       prove it actually works, with fresh evidence
   → evidence-before-claims.  GATE: no "done" without fresh command output.

Phase 6 — REVIEW       an independent pass before it lands
   → reviewing-work (fresh reviewer subagent) and/or consulting-codex.  GATE: findings resolved by severity.

Phase 7 — FINISH       land it the way the human chooses; clean up
   → finishing.  GATE: full suite green; human picks merge / PR / keep.

Build and craft interleave per slice; verify and review gate each meaningful chunk, not just the end.

Commit at Every Green Slice

GREEN EVIDENCE = COMMIT POINT

The moment a slice verifies — fresh output in hand (evidence-before-claims) — commit it on the isolated branch, with the slice as the message. Uncommitted work must never outlive the slice that produced it. A commit is a checkpoint, not a publication: this loop is your standing authority to commit on the work branch; pushing and landing stay human gates (Phase 7).

The excuse	The answer
"I'll commit when it's all done"	Then one bad edit can cost the session. Checkpoint the green.
"It's not clean enough to commit"	Clean is Phase 4's job. Commit the working ugly version — that's the block whittling carves from.
"It'll get squashed anyway"	Fine — squashing later is trivial. Recovering lost uncommitted work isn't.

The Gates Are Inviolable

Three things are the human's call, never yours, no matter the time pressure:

• Phase 0 — approval of what you're building, before any code.
• Phase 7 — how it lands (merge / PR / keep). Discarding work needs an explicit, typed confirmation.
• Anything irreversible, security-sensitive, or externally visible (push, publish, delete, spend).

Everywhere else, decide and record the ruling (in a bead) rather than stalling — momentum over paralysis.

Common Mistakes

• Skipping Phase 0 because the idea "is obvious." Obvious ideas are where scope creep hides. Get buy-in.
• Coding on main. Isolate first (Phase 1), or you can't cleanly abandon a bad path.
• Claiming done from Phase 3. "It compiles" is not "it works." Phase 5 exists for a reason.
• Hoarding changes until Phase 7. A wall of uncommitted work is unreviewable and one mistake from gone. Green slice → commit, every time.
• Running the full loop for a spike. Ceremony must match the work. Classify first.