spec

A spec in traditional agile shape — the full Atlassian ladder, initiative → epics → user stories, with themes as the labels that span them — that opens collapsed to headlines: the initiative's goal, its epics, their story titles; one screen, no scrolling. Click a story for its acceptance criteria; click a criterion for how it will be verified. Themes are "large focus areas that span the organization" — tags, not work items: a catalog shown on the initiative, toggled onto the stories they span (auditability, performance, compliance). The complaint this fixes: a spec today is a long document nobody reads.

wireframe + product.md + the conversation ──► tree JSON ──► drill-down page ──► edits & notes ──┐
                          ▲                                                                     │
                          └────────── you apply it, reply in notes, regenerate ◄────────────────┘
                                             │
                          specs/YYYY-MM-DD-<feature>.md   ← generated every round

The tree is the spec. .vstack/specs/<feature>.json is the source of truth; the markdown under specs/ is generated from it, never edited by hand. There is no approve/reject — the user changes what's wrong, and the change is the feedback.

1 · Draft the tree

Read whatever exists — the wireframe (design/<feature>.html or wherever it lives), specs/product.md, specs/requirements.md, and the conversation. Then write .vstack/specs/<feature>.json:

{
  "feature": "candidate-pipeline",
  "title": "Candidate pipeline",
  "goal": "The epic statement — one sentence on what the user gets.",
  "source": ["design/candidate-pipeline.html", "specs/product.md"],
  "themes": ["Auditability", "Reporting"],
  "epics": [
    { "id": "e1",
      "title": "As a hiring manager, I want to run a role's pipeline in one place, so that no candidate stalls unseen.",
      "stories": [
      { "id": "s1",
        "title": "As a hiring manager, I want to see everyone who applied to a role, so that I can act on every application.",
        "themes": ["Reporting"], "notes": [],
        "note": "Newest application first — the sort is the point, not a detail.",
        "crit": [
          { "id": "c1", "scenario": "Opening a role",
            "given": "Role 42 has applications",
            "when": "I open /roles/42",
            "then": "The top row is the most recent application",
            "and": "", "notes": [] }
        ] }
    ] }
  ]
}

The model is Epic → User story → Acceptance criteria inside one initiative (title + goal, the document itself), with Atlassian's themes spanning it as labels:

• Epics and user stories are both written as "As a [persona], I want to [goal], so that [benefit]". The story is the experience — what the person wants.
• There is no separate requirements list. A requirement that isn't checkable is an opinion, and one that is checkable is a scenario — so it goes in crit, where phase-build will test it. Writing both meant writing everything twice and letting the two drift.
• note is the margin — one optional string per story for the aside that isn't a criterion: a constraint, a decision already taken, a thing not to forget. It is never a hiding place for behaviour that belongs in crit.
• crit are the acceptance criteria, as Gherkin scenarios — scenario names the behaviour; given / when / then (and optional and) make it checkable with real values, not restatements. A criterion you can't write as Given/When/Then isn't done. This is also what phase-build later tests against. Cover the flows, not just the demo path: every story's scenarios should span the happy flow, the sad flows (invalid input, refusals, failures), and the edge cases (empty, duplicate, boundary). One happy scenario alone is a spec that lies by omission.
• doc.themes is the initiative's theme catalog — plain labels, edited here, not on the page; each story's themes array tags it. Keep the catalog short — a theme only one story wears isn't spanning anything.
• No priorities here. Which stories land first is a phasing decision, and phasing is /vstack:user-story-map's job — the spec says what, the story map says when. Ids are stable — never renumber existing ones on a rewrite.
• A small feature is one epic; don't invent a second epic to look thorough. Keep the first pass lean — the loop is how it gets rich; a bloated v1 wastes the user's first round on deletions.