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

# os-sdlc — overview (launching point, v0.1)

Status: scaffold only. No skills/agents/hooks/scripts are implemented yet — this
document exists to anchor a follow-up brainstorming session, not to lock a design.

## Why this plugin exists

Matt Pocock (mattpocock/skills) shipped a v1.1 lifecycle update (2026-07-14) that
turned his skill set from a planning tool into a full grill → to-spec → to-tickets →
implement → code-review → commit pipeline. Separately, `~/dev/delta-refinery` runs a
heavier, DB-backed, multi-level pipeline (System Design → Behavioral Design →
Architecture → Slicer → Requirements) with named agent roles per level and a
Pre/Post/Handoff pattern for resumable multi-agent work.

`os-sdlc` is where cc-os adapts the good parts of both — Matt's lightweight linear
lifecycle and Delta Refinery's structured multi-level handoff discipline — into the
existing os-* family, wired to `os-backlog` (tickets/tracker) and `os-adr` (decision
gate), rather than reinventing either. See
[docs/adr/0037](../../docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md)
for why this is a plugin inside cc-os rather than a separate `cc-sdlc` marketplace.

## Scope: not just skills

Unlike most current cc-os plugins, `os-sdlc` is expected to carry all of:
- **skills/** — the lifecycle verbs (`review` is the first: cherry-picks Matt's
  standards-conformance + spec-fidelity + Fowler refactor-smell axes into a new
  `/os-sdlc:review`, coexisting with the existing generic `/code-review`).
- **agents/** — named roles for pipeline stages, in the spirit of Delta Refinery's
  per-level agent rosters, sized down to what a lightweight harness actually needs.
- **hooks/** — session/state wiring where a deterministic check beats a skill.
- **reference/** — general best-practice material by language/framework/pattern that
  pipeline stages can pull from (not client- or project-specific — that stays in the
  vault).
- **scripts/** — mechanical CLI tooling supporting the above (candidate for the
  ADR-0025 lib/+bin/ Ruby structure once real logic exists).

## Working philosophy this plugin should encode

Carried over verbatim from the brainstorming that led here, because it's the design
target, not just a preference:

- **Draft-then-refine over get-it-perfect-up-front.** Autoresearch-style loop: draft
  an idea, implement a first pass, audit process and outcome, hypothesize an
  improvement, iterate. Applies to both the artifacts os-sdlc produces (specs,
  tickets, code) and to os-sdlc's own design.
- **Goal is throughput at trust, not just automation.** The target is being able to
  automate large chunks of the dev process for big upcoming projects — "move at the
  speed of thought" — which requires the pipeline to be trustworthy enough at each
  stage that skipping human review of that stage is safe, not just fast.
- **Composability with the rest of cc-os is a hard constraint**, not a nice-to-have:
  os-sdlc must interoperate with `os-backlog` (tickets), `os-adr` (decisions),
  `os-vault` (cross-project knowledge) — ADR-023's "os-* plugins cooperate" bet
  applies here directly.

## Known inputs for the follow-up brainstorming session

- Matt Pocock v1.1 lifecycle notes: `docs/matt-pocock-skills-v1.1-notes.md`.
- Delta Refinery structure (facts gathered this session, not yet written up as a
  standalone doc): 5-level `PipelineRunner`/`PipelineOrchestrator`, per-level agent
  rosters under `.claude/agents/{prd,functional_spec,technical_spec,requirements}/`,
  intra-level in-memory `Handoff` + inter-level DB-persisted `Artifact#structured_content`
  for resumability, two composition roots (`HeadwatersComposition` full pipeline vs.
  `ProductionComposition` requirement-level-only).
- Existing cc-os pieces this must integrate with: `os-backlog` (capture/list/route),
  `os-adr` (find/create/init/migrate), `os-vault` (query/write/onboard-project).
- Open question carried into the brainstorm: how much of Delta Refinery's
  resumable-handoff machinery is worth adopting now vs. deferred until a concrete
  multi-session pipeline actually needs it (avoid building it ahead of a real need).

## ADW taxonomy input (2026-07-14 session)

Cross-project methodology reference, not repo-specific: see the vault note
`agentic-sdlc-ai-developer-workflow-taxonomy.md` (SecondBrain) — a taxonomy of AI Developer
Workflow (ADW) structures from IndyDevDan's "Forget Loop Engineering" video (mermaid diagrams
included, with `[dan]`/`[jrs]` provenance tags separating his claims from cc-os-specific
extrapolation). Read it before designing os-sdlc's pipeline shape; the plan below is the
repo-specific slice of that broader taxonomy.

Three actors of value creation apply directly to os-sdlc's component design: **code**
(deterministic, free, most reliable — lint/format/test/CI/ticket-state transitions),
**engineer** (the two fixed constraints: prompting/planning at the start, reviewing at the
end), **agent** (judgment work: planning, building, scouting). Every os-sdlc pipeline stage
should be built by first asking which of the three actors it actually needs — don't default
to "agent" for something code or a human gate should own.

## First-iteration build plan: a single tracer-bullet ADW

Per the vault note's escalation ladder, and per standing tracer-bullet convention, the first
build target is the smallest complete loop, not the software factory. Scope:

**One worktree, one pipeline**: `ticket intake → build agent → lint/format/test (hooks) →
engineer review → ship`. Sandboxes, N-way worktree fan-out, the hotfix ADW, and the software
factory router are explicitly deferred — documented in the vault note, not built here.

Step by step:

1. **Ticket intake** (code, not agent). Reuse `os-backlog` as the trigger: a card moving to
   `Doing` (or a linked Forgejo issue via `/to-tickets`) is the pipeline's entry point. No new
   ticketing system — os-sdlc consumes os-backlog's state, per ADR-0037's composability
   constraint.
2. **Build agent** (agent, minimal tools). New `os-sdlc` agent definition: system prompt scoped
   to "write/modify code to satisfy the spec," tool grants limited to `Read`/`Write`(/`Edit`) —
   no `Bash`. It cannot run tests or linting itself; it only ever sees pass/fail feedback handed
   back to it.
3. **Lint/format/test gate** (code, via hooks — delta-refinery-style Pre/Post/Handoff, not a
   skill-embedded step). A `PostToolUse`-style hook (or a small script the pipeline invokes
   between agent turns) runs the project's lint/format/test commands after each build-agent
   turn. On failure, the failing output is fed back into the *same* build-agent session as the
   next turn's context (per Dan's separation-of-concerns principle). On pass, advance.
4. **Engineer review** (human gate). Standard PR/diff review — no change from how review works
   today; the pipeline's job is to get a clean, tested diff in front of the engineer, not to
   replace this gate.
5. **Ship** (code). Merge + whatever this repo's existing deploy path is — os-sdlc does not
   own deploy; it hands off a mergeable, reviewed change.

Each step above should be walked by hand first (per Dan's second tip) before being wired into
skills/hooks/agents — run the lint/test loop manually against a real small change, confirm the
feedback-loop shape works, *then* automate it.

## Not decided yet (do not assume in implementation)

- Which of Matt's skills get adopted as-is vs. adapted vs. skipped, beyond `review`.
- Whether `implement` is adopted as a thin router as-is, or redesigned as a
  Delta-Refinery-style level with named sub-roles.
- Whether `wayfinder` (multi-issue planning for big-plan decomposition) subsumes or
  sits alongside a Delta-Refinery-style level structure.
- Any hook or agent definitions — none exist yet.