# Hacking Workflow

> 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

- Skill: `atgreen/hacking-workflow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add atgreen/hacking-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/atgreen/hacking-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: atgreen (https://skillmd.com/u/atgreen)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/atgreen/hacking-workflow

---


# 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.