cc-os/plugins/os-sdlc/reference/spec-and-ticket-layer.md

# spec and ticket layer

_Status: settled — grilled 2026-07-17 (open questions resolved)_
_Connects to: [pipeline-stages](pipeline-stages.md), [worktree-parallelism](worktree-parallelism.md), [never-ask-twice](never-ask-twice.md), [overview](../OVERVIEW.md)_

## Purpose

States where specs and tickets live and how a plan becomes an increment `/implement` can
consume. Load this before designing `to-spec`, `to-tickets`, or any skill that reads/writes
issue-tracker state for os-sdlc.

## Design

- **Git issues are the durable spec layer.** Forgejo (via `tea`) or GitHub (via `gh`),
  resolved per-project by the os-backlog tracker key in `.cc-os/config`
  (`forgejo:owner/repo`, `github:owner/repo`, or `repo:path` — ADR-0042). Planka is retired;
  there is no separate os-sdlc storage for specs or tickets.
- **Composability constraint (ADR-0037):** os-sdlc consumes `os-backlog` rather than
  reinventing ticketing. Ticket intake, creation, and listing go through os-backlog's
  `issue-create`/`issues` CLI wrappers, not a parallel os-sdlc data model.
- **Pocock lifecycle mapping**, adapted to the git-issues substrate:
  - **wayfinder** — big plans, new ideas. Free-form exploration, not yet tracker-shaped.
  - **grill-with-docs** — sharpens or decomposes a plan further where user direction is
    genuinely needed (see [never-ask-twice](never-ask-twice.md) for when a question should
    instead be answered by lookup rather than posed here).
  - **to-spec** — publishes the sharpened plan to the issue tracker as a spec-bearing issue
    (or epic-equivalent) — the durable artifact other stages read from.
  - **to-tickets** — decomposes the spec into feature-specific, independently-implementable
    increments, each its own issue, tracer-bullet style. Confirmed 2026-07-16: this is
    Pocock's v1.1 *rename* of `to-issues` ("a spec defines the destination; tickets are the
    journey"), not a sibling — the leftover `to-issues` skill was removed the same day.
  - **`/implement`** — consumes exactly one ticket into the [pipeline-stages](pipeline-stages.md)
    pipeline. One ticket in, one worktree/branch out (see
    [worktree-parallelism](worktree-parallelism.md)).
- The tracker is the single source of truth for spec *and* ticket state — no shadow status
  file. Stage reports (pipeline-stages) update the issue via comments/labels rather than a
  separate os-sdlc-owned record.
## Grilled decisions (2026-07-17)

- **Wayfinder subsumes levels.** No DeltaRefinery-style explicit level hierarchy. A big
  plan becomes a wayfinder decision map on the issue tracker: typed sub-issues
  (research / grilling / prototype / task), blocking relationships between them, each
  sized to one agent session; when all close, the map feeds `to-spec`. Blocking edges
  express what levels used to; this drops the rigidity the DeltaRefinery retrospective
  flagged as a failure mode.
- **Skill adoption verdicts:**
  - **wayfinder — adapt** (keep shape, swap substrate): concept intact — decision map as
    issues, four ticket types, blocking edges, one-session sizing — but every tracker
    interaction goes through os-backlog's `issue-create`/`issues` CLI + tracker key, with
    the cc-os label taxonomy. Verbatim was never on the table: composability with
    os-backlog is a hard constraint (ADR-0037), and Pocock's prose bakes in
    GitHub-specific plumbing (sub-issues, `gh` syntax) Forgejo can't honor.
  - **grill-with-docs — skip; reuse the global `grilling` skill**, both invoked directly
    for small plans and from wayfinder's grilling-type tickets. One grill implementation,
    no drift between copies; the never-ask-twice lookup gate wraps it in one place.
    Accepted cost: os-sdlc depends on a personally-installed global skill — fold a copy
    into the plugin only if os-sdlc ever ships beyond the user's machines.
  - **to-spec / to-tickets — adapt both**: Pocock's semantics (spec = destination,
    tickets = journey) on the os-backlog substrate; all writes via `issue-create` with
    the tracker key; spec→ticket linkage uses plain issue references that work on both
    Forgejo and GitHub; templates are ours (below). Scope note (2026-07-17): os-sdlc's
    `to-spec` does NOT replace the globally installed `to-prd` — os-sdlc is
    software-development specific, while `to-prd` remains the general-purpose PRD
    publisher for non-SDLC work. They coexist; the namespaced invocation
    (`/os-sdlc:to-spec`) keeps them unambiguous.
- **Spec issue template — lean four-section.** Ticket-level detail lives in tickets, not
  the spec, so the spec stays stable while tickets churn. Labels: `spec` + priority;
  tickets reference it as `spec: #NN`.

  ```md
  # <feature name> [spec]

  ## Destination        — what exists when done, 3-6 sentences, observable behavior
  ## Settled decisions  — every choice an implementer must not relitigate (ADR-NNNN refs)
  ## Out of scope       — deferred items + where they went (horizon doc, issue #NN)
  ## Sources            — wayfinder map root #NN, grill transcripts, vault notes, ADRs
  ```
- **Ticket issue template — testable assertions, one-run slice.** Acceptance criteria are
  observable given/when/then assertions the test-writer stage converts to tests
  near-mechanically — batched at one-ticket grain (the DeltaRefinery lesson: drop
  per-example granularity, keep mechanical verification). Sizing rule: a thin end-to-end
  slice fitting one `/implement` run (one worktree, one branch, one review); if the
  criteria won't fit in 3–7 assertions, split the ticket.

  ```md
  # <slice name> [ticket]
  spec: #NN

  ## Slice                — one sentence: the thin end-to-end path added; demoable alone
  ## Acceptance criteria  — 3-7 "Given <state>, when <action>, then <observable result>"
                            checkboxes, each testable without human judgment
  ## Non-goals            — adjacent behavior deliberately left to #NN
  ## Notes for implementer (optional) — known seams, files, gotchas
  ```

## Sources

- ADR-0037 (`docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md`)
- ADR-0042 (2026-07-16, Planka retirement / git-issues-only os-backlog)
- `plugins/os-sdlc/OVERVIEW.md`
- SecondBrain vault: `matt-pocock-skills-v1-1-changes.md`
- `plugins/os-backlog/` (tracker key, `issue-create`/`issues` CLI)
- 2026-07-16 design session (this doc's origin); 2026-07-17 grill session (decisions above)