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: 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.

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 -.spec-gap fail-back.-> 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	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	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	settled	Hooks, not agents, run tests/lint; red/green asserted mechanically; green command pluggable per project
agent-design-principles	settled	Single job, minimal tool allowlist (programmer: no Bash), settled facts in via prompt, minimum out via return format
worktree-parallelism	direction	Worktree-per-spec, sequential tickets within a spec, parallel across specs, human merge gate
pipeline-observability	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	settled (grilled 2026-07-18)	The agency mechanism, ideation-primary: pre-pass lookup → batch mint at settle → audit promotion; two-state readiness (ready-for-agent/ready-for-human) replaces the autonomy trio
self-improvement-loops	direction	Session audits, ADR audits, eval harnesses, skill-lint — each catches a different drift
plugin-factory	direction	Same factory builds plugins from a PRD; the eval harness is the green command
standards-and-conventions	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	direction (deferred)	Stuck-path specialist, distinct from the reviewer; independent reconstruction + diff, feeds harness improvement; not the adversarial reviewer
horizon	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'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. 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'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 and debugger are post-tracer-bullet, built alongside self-improvement-loops — nail the flow first, dial in quality once the happy path is trusted. Everything in horizon 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 (✅ grilled 2026-07-17) → pipeline-stages (✅ grilled 2026-07-18) → never-ask-twice (✅ grilled 2026-07-18; formalization + label-taxonomy ADRs minted) — next up: self-improvement-loops (can run in parallel with pipeline build; owes NAT only the audit cadence number), then horizon. 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)