6.4 KiB

Raw Blame History

spec and ticket layer

Status: settled — grilled 2026-07-17 (open questions resolved) 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. 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. 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.

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.

# <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.
```
# <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)

6.4 KiB Raw Blame History Unescape Escape