| 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
- Create — at task start, scaffold the triplet.
- Update — as work proceeds, check off
plan.md tasks, append findings to context.md.
- Resume — if ending mid-work, write the
## 0. Resume here block.
- 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.
