sdlckit 0.3.3

SDLCKit — AI-governed SDLC lifecycle engine with SAGE loop

SDLCKit

Governed AI quality loops for every SDLC phase.

SDLCKit wraps each phase of the software development lifecycle in a SAGE loop — a governed cycle where humans declare intent, AI produces artifacts, and independent scorers review against weighted quality dimensions. The result: measurable confidence in AI-generated artifacts before they reach production.

SDLCKit is a governance layer, not an SDLC. You keep your existing process and add SDLCKit on top.

---

Why Governance?

AI agents can produce code, specs, and designs — but without governance, there is no measurable quality signal. SDLCKit provides that signal through four properties:

Property	What It Means
Independent Scoring	Scorer agent is sandboxed (read-only tools). Cannot collude with producer.
Dimensional Confidence	Not pass/fail. N weighted dimensions scored independently (e.g., clarity 0.35, completeness 0.30).
Bounded Fix Loops	Max N automated iterations. Oscillation detection stops thrashing.
Human Gates	Two-pass: (1) deterministic structural check, (2) human quality review with scorecard.

---

The SAGE Loop

Every phase — refine, architect, build, review — runs the same governed cycle:

  SCOPE                           SAGE LOOP
  +------------------+            +------------+
  | User input       |       +--->|  ANALYZE   |
  | Discovery output |       |    |  Frame goal + constraints   |
  | Feedback signals |------>+    +-----+------+
  | Prior state      |       |          |
  +------------------+       |          v
                             |    +------------+
                             |    | GENERATE   |
                             |    |  AI produces artifacts      |
                             |    +-----+------+
                             |          |
                             |          v
                             |    +------------+
                             |    | EVALUATE   |
                             |    |  Independent scorer scores  |
                             |    |  N weighted dimensions      |
                             |    +-----+------+
                             |          |
                             |     confidence < threshold?
                             |          |
                             |     YES: Fix Loop (target weakest dim)
                             |          |
                             |     NO:  Human Gate
                             |          |
                             |    [Approve] -> advance
                             |    [Revise]  -> feedback
                             +----[Pause]   -> save state

---

Quick Start

Prerequisites

• Python 3.11+
• An AI coding assistant: Claude Code, GitHub Copilot CLI, Cursor, or Windsurf

Install

pip install sdlckit

Initialize a Project

sdlckit init

Scaffolds your project with sdlc.yaml, skills, templates, schemas, and the /sdlc slash command.

Customize

After init, update these for your team:

• sdlc.yaml — lifecycle phases, scoring dimensions, thresholds, plugin config
• sdlc-memory/conventions/ — layered convention files loaded in sorted order:
  • 00-architecture.md — diagram standards, contract registry format, component identity (built-in)
  • 01-security-architecture.md — trust zones, data classification (built-in)
  • 10-your-team.md, 11-your-domain.md — add your own with 10+ prefix

Run a Phase

# In your AI coding assistant:
/sdlc refine "user onboarding feature"

The SAGE engine produces REFINE.md, scores it across weighted dimensions, runs fix loops if below threshold, then presents the human gate.

Check Status

/sdlc status

---

Commands

Slash commands (in your AI coding assistant):

Command	What It Does
/sdlc <phase> "input"	Run a phase with direct input
/sdlc <phase>	Run a phase (inputs auto-resolved from upstream)
/sdlc <phase> amend "feedback"	Re-enter a completed phase with feedback
/sdlc status	Lifecycle dashboard
/sdlc reconcile	Re-run stale phases after an amendment
/sdlc signal list|show|dismiss|inject	Manage feedback signals

CLI commands:

Command	What It Does
sdlckit init [--type component|initiative]	Scaffold a project
sdlckit assign <path>	Import an assignment into a component repo
sdlckit observe <title> --components <names>	Record an operational observation
sdlckit archive <name>	Pre-merge cleanup (manifests, state)
sdlckit update [--migrate-config] [--dry-run]	Update framework files; optionally migrate config
sdlckit --version	Show installed version

---

Project Layout

After sdlckit init, your project has two state roots:

my-project/
├── sdlc.yaml                          # Lifecycle config
├── sdlc-memory/                       # Persistent state (git-committed)
│   ├── conventions/                   #   Team conventions (customizable)
│   ├── contracts/                     #   Contract registry + spec files
│   │   └── registry.yaml             #   Components, contracts, interfaces
│   ├── knowledge/                     #   Patterns and anti-patterns (YAML)
│   ├── components/                    #   Component profiles (YAML)
│   ├── observations/                  #   Operational observations
│   └── work/                          #   Per-initiative work artifacts
├── .sdlckit/                          # Runtime state (gitignored)
│   ├── runtime/lifecycle-state.yaml   #   Phase state, tokens, timestamps
│   ├── events.jsonl                   #   Event log
│   ├── feedback/                      #   Feedback signals
│   └── reconciliation/                #   Reconciliation sessions
└── .claude/                           # AI harness files (or .codex/, etc.)
    ├── skills/sdlc-*                  #   Phase and CLI skill wrappers
    ├── commands/sdlc.md               #   /sdlc slash command
    └── sdlckit/                       #   SAGE engine core + templates

---

Two Modes

Component mode (sdlc.yaml) — single project, linear phase sequence: refine -> architect -> build -> review.

Initiative mode (sdlc-initiative.yaml) — multi-component, multi-repo projects. Discovery and Delivery stages with per-component SAGE loops, stage reviews, knowledge extraction, and assignment handoffs.

---

Extending with Plugins

SDLCKit separates engine (how the loop runs) from domain knowledge (what the loop produces). Plugins provide richer implementations:

• Phase plugins replace built-in phases with specialized skills, agents, dimensions, and templates
• Connector plugins deliver scored artifacts to external systems (Jira, CI/CD, etc.)

See docs/developer-guide.md for plugin authoring.

---

Architecture Decision Records

Design decisions for medium-to-complex changes are documented as ADRs in docs/adr/. Pull requests should reference the relevant ADR.

See docs/adr/README.md for the format and process.

---

Documentation

• Consumer Guide — installation, configuration, daily usage
• Contributor Guide — engine internals, testing
• Developer Guide — building plugins, skills, agents, schemas
• AGENTS.md — AI assistant rules (MUST/SHOULD for Claude, Copilot, Cursor, etc.)
• Architecture Reference — SAGE engine, state management, plugin model, agent model
• ADRs — architecture decision records
• Reverse Architect Quickstart — scan existing codebases

---

License

Apache License 2.0