2026-07-16 19:39:35 +00:00
|
|
|
# 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
|
2026-07-16 20:08:23 +00:00
|
|
|
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.
|
2026-07-16 19:39:35 +00:00
|
|
|
- **`/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).
|
|
|
|
|
|
|
|
|
|
## 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`
|
2026-07-16 20:08:23 +00:00
|
|
|
- `plugins/os-backlog/` (tracker key, `issue-create`/`issues` CLI)
|
2026-07-16 19:39:35 +00:00
|
|
|
- 2026-07-16 design session (this doc's origin)
|
