# spec and ticket layer

_Status: settled direction — as of 2026-07-16_
_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 (same shape as the existing
    `to-issues` skill, but scoped to a published spec rather than an ad hoc plan).
  - **`/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.
- Spec and ticket content structure is intentionally not fixed yet (see Open questions) —
  the mapping above fixes *where* things live and *what stage produces them*, not their
  internal template.

## Open questions

- Which Pocock skills (wayfinder, grill-with-docs, to-spec, to-tickets) are adopted
  near-verbatim vs. adapted for the git-issues substrate vs. skipped entirely.
- Whether wayfinder subsumes or sits alongside a DeltaRefinery-style level structure
  (DeltaRefinery decomposed work into explicit levels; Pocock's wayfinder is looser).
- Concrete spec issue template (sections, required fields) and ticket issue template
  (acceptance criteria shape, tracer-bullet slice size).
- Whether `to-tickets` reuses the existing `to-issues` skill directly or needs its own
  spec-aware variant.

## 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, `to-issues` skill)
- 2026-07-16 design session (this doc's origin)