cc-os/plugins/os-sdlc/OVERVIEW.md

# os-sdlc — overview & concept map (v0.2)

_Last updated: 2026-07-17. Status: design mapped, no implementation yet._
_This is the single entry point: an AI pointed here loads only the reference/
nodes its task needs, following the map below._

## Why this plugin exists

Blend two proven inputs into one harness-driven SDLC "factory":

- **Matt Pocock's v1.1 skill lifecycle** (wayfinder/grill → to-spec → to-tickets →
  implement → code-review → commit) — lightweight, linear, skill-shaped. Notes:
  SecondBrain vault note `matt-pocock-skills-v1-1-changes.md`.
- **DeltaRefinery** (`~/dev/delta-refinery`) — the user's prior multi-level pipeline.
  Retrospective (2026-07-16): keep its virtues — everything deterministic is
  mechanical; single-job agents with minimal read/communicate/tool surfaces;
  hook-run tests (the programmer never runs its own tests). Drop its failure
  modes — headless-run allotment cost, and per-example TDD granularity (batch to
  one-ticket grain instead).

Placement and scope are decided in
[docs/adr/0037](../../docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md):
a plugin inside cc-os carrying skills + agents + hooks + reference + scripts,
composing with `os-backlog` (git issues — Planka retired by ADR-0042), `os-adr`,
`os-vault`, and `os-context` rather than reinventing any of them.

## Concept map

Each node is an independent context in `reference/`. Edges are "design here
constrains/feeds design there." Decomposing a node into tickets = grill its
"Open questions" section, then `to-spec` → `to-tickets` as usual.

```mermaid
graph TD
    ST[spec-and-ticket-layer] --> PS[pipeline-stages]
    PS --> DG[deterministic-gates]
    PS --> AD[agent-design-principles]
    PS --> WP[worktree-parallelism]
    DG --> PF[plugin-factory]
    PS --> PO[pipeline-observability]
    PS -.blocked stage.-> NAT[never-ask-twice]
    NAT <--> SIL[self-improvement-loops]
    PO --> SIL
    SIL --> PF
    DG -.post-v1.-> SC[standards-and-conventions]
    SC -.residue.-> PS
    NAT -.pre-seed.-> SC
    DG -.stuck/post-v1.-> DBG[debugger]
    DBG --> SIL
    PS -.deferred.-> HZ[horizon]
    WP -.deferred.-> HZ
    NAT -.mobbin.-> HZ
    DBG -.adversarial.-> HZ
```

## Index

| Node | Status | One-liner |
|---|---|---|
| [spec-and-ticket-layer](reference/spec-and-ticket-layer.md) | settled direction | Git issues (Forgejo/GitHub per tracker key) are the durable spec layer; Pocock verbs map onto it |
| [pipeline-stages](reference/pipeline-stages.md) | direction | The v1 tracer bullet: `/implement` → test-writer → red-assert → programmer → green-assert → reviewer → human merge |
| [deterministic-gates](reference/deterministic-gates.md) | settled | Hooks, not agents, run tests/lint; red/green asserted mechanically; green command pluggable per project |
| [agent-design-principles](reference/agent-design-principles.md) | settled | Single job, minimal tool allowlist (programmer: no Bash), settled facts in via prompt, minimum out via return format |
| [worktree-parallelism](reference/worktree-parallelism.md) | direction | Worktree-per-spec, sequential tickets within a spec, parallel across specs, human merge gate |
| [pipeline-observability](reference/pipeline-observability.md) | direction | What a run writes down (exhaust), where it lives, predefined lifespans (os-doc-hygiene); copy-tag-audit pattern feeds the loops |
| [never-ask-twice](reference/never-ask-twice.md) | direction | The agency mechanism: two-tier lookup → mint-time scope classification → audit promotion; decision-category autonomy labels |
| [self-improvement-loops](reference/self-improvement-loops.md) | direction | Session audits, ADR audits, eval harnesses, skill-lint — each catches a different drift |
| [plugin-factory](reference/plugin-factory.md) | direction | Same factory builds plugins from a PRD; the eval harness is the green command |
| [standards-and-conventions](reference/standards-and-conventions.md) | direction (Option B decided) | Author a standard once; three layers (opinion/bindings/adoption); lint-enforceable rules stay in nobody's prompt, only judgment residue reaches the reviewer |
| [debugger](reference/debugger.md) | direction (deferred) | Stuck-path specialist, distinct from the reviewer; independent reconstruction + diff, feeds harness improvement; not the adversarial reviewer |
| [horizon](reference/horizon.md) | horizon | Wake-on-trigger, Herdr controller, router agent, Mobbin, adversarial reviewer — preserved intent, explicitly out of v1 |

## Working philosophy (design target, not preference)

- **Draft-then-refine over get-it-perfect-up-front** — applies to the factory's
  artifacts and to the factory itself.
- **Throughput at trust, not just automation** — a stage is done when skipping
  human review of it is *safe*; trust is earned in units and made durable
  (see never-ask-twice).
- **Three actors** (vault note `agentic-sdlc-ai-developer-workflow-taxonomy.md`):
  every stage first asks whether it needs **code** (deterministic, free),
  **engineer** (fixed start/end gates), or **agent** (judgment) — never default
  to agent.
- **Composability with os-* siblings is a hard constraint** (ADR-023).

## Build sequencing

v1 = the tracer bullet in [pipeline-stages](reference/pipeline-stages.md),
triggered manually, walked by hand once with disposable code and trivial prompts
before wiring into skills/hooks/agents. **Code quality is deliberately a later
phase:** [standards-and-conventions](reference/standards-and-conventions.md) and
[debugger](reference/debugger.md) are post-tracer-bullet, built alongside
[self-improvement-loops](reference/self-improvement-loops.md) — nail the flow
first, dial in quality once the happy path is trusted. Everything in
[horizon](reference/horizon.md) stays unbuilt until the interactive factory is
trusted. Open items live per-node in each doc's "Open questions" — this file
carries none.

**Grill queue** (decided 2026-07-16): the critical path is
[spec-and-ticket-layer](reference/spec-and-ticket-layer.md) →
[pipeline-stages](reference/pipeline-stages.md) — grill in that order first.
Then [never-ask-twice](reference/never-ask-twice.md) +
[self-improvement-loops](reference/self-improvement-loops.md) (can run in
parallel with pipeline build; NAT's formalization ADR is independent), then
[horizon](reference/horizon.md). The remaining nodes' open questions are
implementation-time calls, not grill material.

## Sources

- Vault: `matt-pocock-skills-v1-1-changes.md`, `agentic-sdlc-ai-developer-workflow-taxonomy.md`
- Repo: ADR-0037 (placement), ADR-0042 (git-issues-only backlog), `~/dev/delta-refinery`
- Tracked follow-ups: cc-os Forgejo issues #71 (audit criteria), #72 (skill-lint), #73 (worktree tracker resolution)