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

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

_Last updated: 2026-07-18. 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 (grilled 2026-07-17) | Git issues are the durable spec layer; wayfinder subsumes levels; adapt wayfinder/to-spec/to-tickets, reuse global grilling; spec + ticket templates fixed |
| [pipeline-stages](reference/pipeline-stages.md) | settled (grilled 2026-07-18) | The v1 tracer bullet: `/os-sdlc:implement` → test-writer → red-assert → programmer → green-assert → reviewer → human merge; agent naming, from-scratch orchestrator prompt, and pre-programmer-review all resolved |
| [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).
- **Observed-failure-first** — no standing stage, agent split, or prompt instruction is added
  preemptively; each exists only in response to an observed failure (an audit finding, an
  eval miss, a broken run), and audits are the trigger to revisit. This rule already decided
  [pipeline-stages](reference/pipeline-stages.md)'s no-programmer-split, no-refactor-stage,
  and no-pre-programmer-review calls; at the prompt-wording level it's the same rule as
  ADR-0044 (minimal-prompt discipline).

## Four phases

| Phase | Who/what | Mechanism |
|---|---|---|
| Ideation | User + AI | grill → to-spec |
| Decomposition | to-tickets skill, acting as the PM | sizing rule: 3–7 Given/When/Then criteria enforced in the ticket template |
| Implementation | `/os-sdlc:implement` pipeline | test-writer → gates → programmer → reviewer |
| Acceptance | Human merge gate | orchestrator presents, human merges; worktree per spec deleted after merge |

## Build sequencing

v1 = the tracer bullet in [pipeline-stages](reference/pipeline-stages.md). Sequence, in
order:

1. **Walk once** — the tracer bullet is performed by hand, once, in a real git worktree,
   with disposable code and trivial prompts, `.cc-os/config` manually copied in to work
   around [worktree-parallelism](reference/worktree-parallelism.md)'s Forgejo issue #73. This flushes
   out the real choreography before anything is wired.
2. **Wire** — the proven choreography is built into skills/hooks/agents. The native fix for
   issue #73 (walk-up to repo root vs. provision-at-creation — the choice is informed by what
   the walk showed) is a hard dependency of this step.
3. **Commissioning ladder** — once wired, a named build phase runs the pipeline through
   progressively harder challenges (complexity more than size), each deliberately designed to
   trip the AI up. Every run is tri-audited — Fable, Codex, and the human — with fixes applied
   lint-first, prompt-second (per ADR-0044's minimal-prompt discipline). Lint/prompt changes
   merge to main; app worktrees used for the challenges are disposable. The same problem
   repeats until the pipeline nails it without help, then the ladder climbs a rung; it
   continues until confidence is ~99% or returns diminish.

**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) (✅ grilled 2026-07-17) →
[pipeline-stages](reference/pipeline-stages.md) (✅ grilled 2026-07-18) — next up:
[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)