SDLC
Status: open/active
Summary
Section titled “Summary”- The SDLC plugin: a software-development-lifecycle tool whose entire state is markdown +
frontmatter on disk, operated by the
sdlc <noun> <verb>CLI and Claude Code skills, and driven hands-off by an orchestration loop. - Self-hosting: the model that plans the tool is built from the tool’s own entity definitions.
- Five-layer architecture — entity substrate up through the orchestration loop — with the same capability runnable from shell, CI, or a Claude session.
What it is
Section titled “What it is”SDLC is a software-development-lifecycle tool whose entire state is
markdown + frontmatter on disk, operated by a single
sdlc <noun> <verb> CLI and a set of Claude Code skills, and driven —
when you want it hands-off — by an orchestration loop. It manages its
own development with its own machinery (self-hosting): the model it
uses to describe its work is built from its own entity definitions.
The why lives in vision; this entity is the how.
Boundary
Section titled “Boundary”This Product is the plugin — its skills, the sdlc CLI, the entity
model, and the validator framework. It is distinct from the sibling
products the project will spin out:
- OSS libraries — general-purpose pieces extracted from the plugin (e.g. the lease protocol, the entity-definition machinery) and shipped standalone.
- The harness — the runtime that operates the plugin (Claude Code
today; the target end state is a provider-agnostic server/client per
vision).
Each sibling becomes its own Product — with its own Drivers and Goals — when it earns its way in.
The bet
Section titled “The bet”Three convictions shape every design decision. The full principle set
(grouped Product / Technical / Project / LLM-AI) is in M-0000 and
indexed in index; the load-bearing three:
| Conviction | What it means | Anchors |
|---|---|---|
| Long-lived, legible substrate | Plain files a human reads and git versions outlast any database or harness; the system survives the tools that operate it. | P-0007-long-lived-data-formats, P-0008-harness-agnostic-substrate |
| Deterministic where it has hardened | An LLM interprets freeform input at the edge; the effect underneath is structured, testable, LLM-free. The head/tail split the CLI is built on. | P-0001-prefer-deterministic-over-llm, P-0005-schema-over-prose |
| Operationalize the work | Every activity becomes an invokable operation that emits structured state, so the project can act on its own signals. | P-0002-operationalize-activity, P-0010-capture-aggregate-act-on-signals |
The model — what SDLC stores
Section titled “The model — what SDLC stores”Everything SDLC tracks is an entity: a markdown file with a schema. Entities are grouped into five layers (D-0003-datamodel-categorization):
| Layer | Entities (status) |
|---|---|
| Product | Product / Driver / Goal — planned |
| Architecture | Capability (drafted) / Constraint — planned |
| SDLC | Requirement / AcceptanceCriterion — planned |
| Work | Milestone, Task — active; Backlog — active; Epic — retired → parent_key (migrates in M-ML68) |
| Planning-meta | Decision, Standard, Principle — active |
The question each layer answers is in D-0003-datamodel-categorization.
Three design pieces give the model its shape:
- The roster — every entity type, its layer, status, and target filename shape — is authoritative in D-ORMG-data-model.
- The why → what → verify chain — Product → Driver → Goal → Capability → Requirement → AcceptanceCriterion — threads the layers so any unit of work traces up to a motivation and down to a test. Designed in D-7F2M-why-what-verify-chain.
- The Products & Drivers — the model is multi-product (the SDLC
plugin, extracted OSS libraries, the harness), and Drivers/Goals scope
to a Product. This is the first drafted Product; the Drivers
instantiate the why end of the chain by
kind(pain-point / use-case / opportunity).
Identity is a random base-36 id per entity (collision-free across parallel branches), with the slug optional and the filename immutable (D-0002-entity-identifier-shape). Each entity ships a complete definition surface — schema, body manifest, template, scaffold, definition doc — per S-0005-entity-definition-contract.
The architecture — how SDLC operates the model
Section titled “The architecture — how SDLC operates the model”Five layers, each knowing only the one below: entity substrate → model framework
(validate/audit/migrate) → sdlc CLI → skill layer → orchestration loop. The full map — stack
diagram, the sdlc <noun> <verb> surface, the three-doors head/tail model, the orchestration tick,
and the validator framework — is in D-VSLI-distributed-work-runner-architecture.
The one inversion worth stating at product level: context-polymorphism. The same capability runs from a plain shell, from CI, or inside a Claude session, because the effect is a deterministic CLI tail and only the freeform-interpretation head changes per context (S-0004-sdlc-cli-llm-head-deterministic-tail). Coordination across parallel agents and branches is serverless — a git ref is the lease (github-ref-leases).
What SDLC does — the capability map
Section titled “What SDLC does — the capability map”The Capability tree is the map of what the system can do, at every
granularity. Today it is fully worked out for one area — Executable
Task (C-0001 plus nine lifecycle sub-features, all verified); the
other areas are map entries, not yet entity files. Each becomes
drafted Capability entities — with schema.json and the full S0005
surface — when its milestone schedules it, per the “earn their way in”
stance (D-ORMG-data-model). The Executable Task tree is the exemplar
of the shape.
Seven top-level areas. Executable Task is the spine; the others either support it (improve intake, definition, review) or build on it (batch it, plan it, keep it healthy). “Surface today” is the skills / CLI that deliver it; “Capability” is whether the area is modeled as a Capability entity yet.
| Area | Serves | Surface today | Capability entity |
|---|---|---|---|
| Executable Task (C-0001) | DR-0007 | task-new/define/ensure-ready/work/review/close-out, pr-check/respond, spawn-task-pr; sdlc task | shipped (C-0001…C-0010) |
| Capture & triage | DR-0006 | backlog-capture, backlog-triage; sdlc backlog | planned |
| Planning | the work above the task | milestone-new, milestones-from-file, roadmap; sdlc milestone (planned) | planned |
| Orchestration | DR-0001, DR-0005 | orchestrate (+ /loop); git-ref leases | planned |
| Model management | DR-0009 | entities-audit, entities-migrate, *-new scaffolds, validators; sdlc entities (planned) | planned |
| Adoption & setup | onboard a repo onto SDLC | setup, import-planning, migrate, migrate-runtime-state | planned |
| Insight & maintenance | keep project state healthy | status-dashboard, find-quality-checks, review-todos, project-cleanup, update-skill-doc | planned |
SDLC capabilities├─ Executable Task [C-0001] ← shipped; surface shipped│ └─ intake · define · ensure-ready · work · review ·│ pr-check · pr-respond · close-out · spawn [C-0002..10]├─ Capture & triage ← surface shipped; capability planned├─ Planning ← partial├─ Orchestration ← surface shipped; capability planned├─ Model management ← partial├─ Adoption & setup ← surface shipped; capability planned└─ Insight & maintenance ← surface shipped; capability plannedThe areas are peer roots today (each parent_key: null, like C-0001).
Whether a single product-level root capability sits above them is left
open — it earns its way in only if a real query needs the rollup.
Areas in detail
Section titled “Areas in detail”| Area | What it does |
|---|---|
| Executable Task (spine; C-0001, drafted) | The one area fully modeled. A task walks idea → merged code through a staged lifecycle, one named operation per transition (C-0002 intake, C-0003 define, C-0004 ensure-ready, C-0005 work, C-0006 review, C-0007 pr-check, C-0008 pr-respond, C-0009 close-out, C-0010 spawn). Tightened end-to-end with task kinds in M-VRVE. |
| Capture & triage (stem-cell intake) | Jot a stray idea in one line; it becomes a tracked Backlog entity, later promoted (with a likely_type hint) to a Task / Milestone / Goal / Driver. Serves DR-0006; feeds C-0002. |
| Planning (work above the task) | Author and order the larger units: Milestones (and the roadmap manifest), and — as the Product/SDLC layers land — Goals, Drivers, Requirements. The why → what → verify chain (D-7F2M-why-what-verify-chain) is this area’s data model. |
| Orchestration (batch the spine) | Drive the loop hands-off: per tick, reconcile PRs, count in-flight work, claim ready tasks under leases, dispatch task-work sub-agents. Serves DR-0001 (removes toil) and DR-0005 (hands-off motion); scaled to milestone/backlog scope in M-QDQ4. |
| Model management (self-host the entities) | Keep the entity model honest: scaffold from the S-0005-entity-definition-contract surface, validate frontmatter + body manifests, audit drift, auto-migrate across schema versions. Serves DR-0009; the validator framework is M-ML68 work. |
| Adoption & setup (onboard a repo) | Bring an existing repository onto SDLC: install the substrate, import pre-existing planning docs, migrate runtime state. The on-ramp for a project that isn’t SDLC itself. |
| Insight & maintenance (keep state healthy) | Surface the project’s shape and tend it: status dashboards, quality-check discovery, TODO review, cleanup, skill-doc upkeep. The aggregate-and-act half of P-0010-capture-aggregate-act-on-signals. |
Use-case → capability index
Section titled “Use-case → capability index”The use-case-kind Drivers map directly onto an area:
| Use-case (Driver) | Capability area |
|---|---|
| DR-0007 idea → merged code | Executable Task |
| DR-0006 frictionless capture | Capture & triage |
| DR-0005 hands-off forward motion | Orchestration |
| DR-0008 operate from any context | cross-cutting — the CLI head/tail property, not one area (D-VSLI-distributed-work-runner-architecture) |
Several pain-points are resolved by architecture or model
properties rather than a single capability: DR-0002 (one CLI surface)
and DR-0008 by the sdlc dispatcher + head/tail split; DR-0003
(parallel collisions) by base-36 ids + leases; DR-0004 (traceability)
by the why → what → verify chain. The opportunities DR-0009
(self-host) and DR-0010 (substrate) are realized by Model management
and the substrate stance, respectively.
Design tenets & non-goals
Section titled “Design tenets & non-goals”- Markdown is the system, not a cache. A future query index or web UI is a materialized view; the files stay the single source of truth. A bidirectional DB↔markdown sync layer is rejected outright.
- Entities earn their way in. A type joins the active roster when real work needs it, not speculatively. The absence of an entity is the default.
- One shared CLI, thin skills. The effect lives in
solutions/ontological/cli/(a deliberate shared system); a skill is a thin head that shells to it (S-0001-co-locate-first-promote-when-shared, S-0002-no-sdlc-carveouts-in-general-skills). - Multi-product — see Products.
- Non-goals: no database of record; no auto-merge of PRs; no detection or evasion machinery. The human merges; the loop shepherds.
Drivers & goals
Section titled “Drivers & goals”The Drivers scoped to this Product are drafted under Drivers; every current Driver is an SDLC-product Driver. Goals attach here once the Product layer schema ships.
Status
Section titled “Status”active — in development, self-hosted against its own machinery.
References
Section titled “References”- Vision & order:
vision·index(milestones byversion) - Model: D-ORMG-data-model · D-7F2M-why-what-verify-chain · D-0003-datamodel-categorization · D-0002-entity-identifier-shape · S-0005-entity-definition-contract
- Architecture: D-VSLI-distributed-work-runner-architecture · S-0004-sdlc-cli-llm-head-deterministic-tail · sdlc-cli · github-ref-leases
- Capabilities: C-0001 (worked-out exemplar)
- Index:
index