spec

name	spec
description	Turn the current conversation and codebase understanding into a work bundle with SPEC.md — synthesis of what is already known, interviewing only on material open forks. Use for unresolved ideas, requirements, sources, system maps, or plans.

spec

Create or revise the bundle's SPEC.md — the file that holds what's needed to do the work. Synthesize what you already know; do not interview. Ask only when a material fork is genuinely open and the answer changes the work.

Readiness gate

Before anything else, count the material forks the conversation leaves open. More than two forks still open → stop and run scout first, letting its table pick the mode per unknown (grill, questionnaire, research, prototype, model); too foggy to state even the problem → scout wayfind. Route to scout at most once per invocation, and when it returns, resume here with the forks it closed — stragglers are settled inline via step 3, not another round trip.

Also confirm the work warrants a bundle: hitting no Full-tier trigger and not an explicit request for a spec → the session task list is enough; stop, no bundle. An explicit request for a spec always gets one.

Process

1. Ground in the repo: read .waymark/MEMORY.md if present, explore the current state, and read .waymark/CONTEXT.md and .waymark/adr/ entries near the touched area — the spec speaks the glossary's language and respects recorded decisions. A repo that already carries a .spec-workflow/ directory keeps that name: read every .waymark/ path in this workflow as .spec-workflow/ there, and do not create a second directory.
2. Check .waymark/active/ and .waymark/paused/; resume a matching bundle instead of creating a twin. While checking, close on sight any bundle whose scope already shipped (its commits are on the target branch), per the bundle contract's close rule. Scan the remaining open bundles' Implementation Decisions and adr/ for locked choices this scope touches; a contradiction is a material fork — settle it now via step 3, not as a mid-implement surprise. Otherwise open one: mkdir -p .waymark/active/<work-id> (short kebab-case work-id). If .waymark/.gitignore is missing, create it with exactly active/, paused/, archive/ (one per line).
3. Settle remaining material forks through scout, by kind — interdependent user decisions via grill, absent-owner decisions via questionnaire, external facts via research, feel-right design questions via prototype, fuzzy terms via model. Forks the conversation already settled are synthesized, never re-asked. An external claim entering the SPEC (API behavior, library semantics, versions) comes from research against primary sources, never from memory.
4. Write SPEC.md from the template below.
5. Harvest what outlives the task: a new domain term this spec settled → add it to .waymark/CONTEXT.md (create lazily, context-format); an Implementation Decision that is hard to reverse, surprising without context, AND the result of a real trade-off → write .waymark/adr/NNNN-<slug>.md (adr-format) plus one index line in MEMORY.md, and let the SPEC link the ADR instead of restating its why.
6. Sketch the seams where behavior will be tested. Prefer existing seams, at the highest level possible; the fewer the better — the ideal number is one. Confirm new or surprising seams with the user.
7. Draft VERIFY.md's scenario skeleton from Testing Decisions: one scenario per red test — behavior, seam, command, expected result — plus one check per Anti-goal. Leave results empty.
8. Seed NOTES.md with Current State, Next Action, and Base: <commit>.

A spec authorizes nothing. Implementation starts only on explicit request, via implement.

SPEC.md template

## Problem Statement
<the problem, from the user's perspective>

## Solution
<the solution, from the user's perspective>

## User Stories
<numbered "As a <actor>, I want <feature>, so that <benefit>" list — when the
work is feature-shaped; omit for fixes and internal changes>

## Implementation Decisions
<modules touched, interfaces, schema and API contracts, architectural choices,
technical clarifications. Each decision names the rejected alternative and why,
in one line; a decision with an         
     —      
    ( ,  ,  )   ,
    >





 the system SHALL " where that sharpens the
one-behavior-one-test mapping. Existing behavior the change must not break is
phrased "the system SHALL CONTINUE TO " and guarded by a
baseline or regression scenario, so preservation is checkable, not assumed.
Note prior art for similar tests in this repo. For work with no executable
seam (docs, config) or behavior-preserving work (upgrades, refactors), the
red list is VERIFY.md scenarios — readback, diff, or a captured baseline —
not tests>