spec-workflow

name

spec-workflow

description

When a task needs a spec (and when it doesn't), the slim/full tier scaffold, and the spec lifecycle. A spec is a durable record of WHAT was built and WHY — it survives compaction and session boundaries. ROUTE BY INTENT — load when starting a multi-step task ("이거spec 만들자", "spec for this feature", starting work that will span multiple commits/sessions), when deciding whether a task is big enough to spec, or when resuming work from a prior spec. NOT for tiny one-off fixes (a spec on a 1-line typo fix is net-negative ceremony).

Spec workflow — durable task records

A spec is a markdown record of what a task is, its plan, and its context. It exists so a task survives compaction and session boundaries — when you (or a fresh session) come back, the spec tells you where you were.

When to spec (and when not)

Spec it	Skip the spec
≥2 sub-components / sub-directories touched	Single-file fix
≥3 commits expected	1-2 commit change
New architectural decision needed	Following an existing pattern
Forward-only measurement required (you'll want to compare before/after)	Throwaway spike
Touches the harness itself (.zcode/, hooks, agents)	Doc-only tweak

Spec ceremony on small work is net-negative. If a task is a typo fix or a one-function follow-up, just do it — a spec adds overhead without value.

The spec scaffold

specs/<YYYYMMDD>-<slug>/
├── spec.md       ← WHAT + WHY (the intent — survives even if the plan changes)
├── plan.md       ← HOW (the task list — checked off as work proceeds)
└── context.md    ← the grounding (files, prior decisions, constraints)

• spec.md — Problem statement, success criteria, scope (in/out), the decision being made and its alternatives. This is the part that should still make sense in 6 months.
• plan.md — A numbered task list with checkboxes. Each task is small enough to verify independently. Mark tasks [x] as they complete.
• context.md — File paths touched, prior ADRs consulted, constraints discovered, links to related specs. The "if you're new to this task, read here first" file.

Tier selection

• Slim tier (single-component change, internal experiment): spec.md + plan.md only. Skip context.md if the spec is self-contained.
• Full tier (≥2 components OR public-facing surface): all three files, full detail.

The resume block (## 0. Resume here)

If work ends mid-task, the LAST thing to do before closing the session is append a ## 0. Resume here block to spec.md:

## 0. Resume here
- Original ask (verbatim): "<the user's exact request>"
- Done so far: <1-3 bullets>
- Next concrete action: <the single next step>
- Blocked on / waiting: <if anything>

A fresh session reads this first — it re-surfaces the original ask (which drifts after compaction) and the exact next step. This is the single most valuable anti-drift mechanism.

Spec lifecycle

1. Create — at task start, scaffold the triplet.
2. Update — as work proceeds, check off plan.md tasks, append findings to context.md.
3. Resume — if ending mid-work, write the ## 0. Resume here block.
4. Close — when done, mark plan.md all [x], add a closing note to spec.md with the verdict and any follow-ups.

A spec is NOT a permanent document — it's a task record. Once the task is done and merged, the spec is history. Don't maintain specs as living docs; that's what ADRs are for.