100 lines
5.7 KiB
Markdown
100 lines
5.7 KiB
Markdown
# os-sdlc — overview & concept map (v0.2)
|
|
|
|
_Last updated: 2026-07-16. 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
|
|
PS -.deferred.-> HZ[horizon]
|
|
WP -.deferred.-> HZ
|
|
NAT -.mobbin.-> 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 |
|
|
| [horizon](reference/horizon.md) | horizon | Wake-on-trigger, Herdr controller, router agent, Mobbin — 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 before wiring into skills/hooks/agents.
|
|
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)
|