jared
/
cc-os
1
0
Fork 0
Code Issues 18 Pull Requests Packages Projects Releases Wiki Activity
cc-os/plugins/os-sdlc/reference/spec-and-ticket-layer.md

3.4 KiB
Raw Blame History

spec and ticket layer

Status: settled direction — as of 2026-07-16 Connects to: pipeline-stages, worktree-parallelism, never-ask-twice, overview

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 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. One ticket in, one worktree/branch out (see worktree-parallelism).
  • 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)