Getting Started

Get up and running with the AI-SDLC Framework.

New adopter? Start here: Onboarding: Clean Clone to First Attested PR — a numbered walkthrough covering prerequisites, install, signing-key init, scaffold setup, first task execution, and first attested PR, with copy-pasteable commands, expected output for each step, and a "Found Gaps" section documenting every hidden prerequisite discovered during development. End-to-end validation on a clean, non-author repository is pending (AC#2 — see the guide for details).

What is AI-SDLC?

AI-SDLC is a Decision Engine for autonomous AI software development. It's the contract-to-shipped half of a spec-driven development stack: you (or a front-of-funnel tool like GitHub Spec Kit) hand it a well-specified contract; AI-SDLC dispatches autonomous agents, enforces quality gates, attests every change, and routes every decision to the right human actor. It provides:

• Decision Engine substrate — operator-as-decision-steward; every architectural / quality / autonomy decision routes through the Decision Catalog (RFC-0035)
• Spec-kit bridge — cli-import-spec / /ai-sdlc import-spec consumes spec-kit tasks.md, runs the DoR Gate at import, and lands governed backlog tasks ready for dispatch (RFC-0036). Recommended adopter authoring path.
• Agent-agnostic orchestration — works with Claude Code, GitHub Copilot, Cursor, OpenAI Codex, or any LLM API
• Structured pipelines that route tasks through defined stages based on complexity
• Quality gates with three-tier enforcement (advisory, soft-mandatory, hard-mandatory)
• Progressive autonomy where agents earn trust through demonstrated reliability
• Codebase intelligence — complexity analysis, pattern detection, hotspot identification, episodic memory
• Adapter contracts that decouple your pipeline from specific tools
• Tamper-evident audit logging for every action taken

Everything is declared as YAML resources validated against JSON Schema, following the same patterns as Kubernetes and other infrastructure-as-code systems.

The recommended adopter authoring path

AI-SDLC supports three artifact altitudes (RFC → Spec → Task; see docs/concepts/spec-driven.md). For day-to-day feature work, the recommended path uses GitHub Spec Kit as the front-of-funnel tool and the spec-kit bridge to land tasks in the AI-SDLC backlog:

spec-kit  ──────►  cli-import-spec  ──────►  AI-SDLC backlog  ──────►  /ai-sdlc execute
(idea →            (DoR Gate at                (governed tasks            (autonomous
 contract)          import; refuse              passing the                 dispatch +
                    + emit clarification        quality contract)            reviewers +
                    upstream on failure)                                     attestation +
                                                                             merge)

The bridge is the seam between authoring and execution. Each side evolves independently:

• Front of funnel (your choice): spec-kit, an adopter RFC scaffold, Linear, Notion, plain markdown. As long as the output is translatable to spec-kit-style tasks.md, AI-SDLC consumes it. Spec-kit is recommended because its mature integrations and /speckit.analyze cross-artifact consistency check compose cleanly with the DoR Gate.
• Back of funnel (always AI-SDLC): DoR Gate → PPA → execute → cross-harness review → attest → merge.

Start here: Tutorial 10 — Spec-Kit Bridge end-to-end walkthrough. Authors a feature in spec-kit, imports it, walks through DoR-at-import + analyze auto-resolution + the upstream-clarification feedback loop, dispatches, and ships. Use this if you want the recommended adopter authoring path end-to-end.

Spec-kit is recommended, not required. Adopters can author backlog tasks directly without any upstream tool. The framework's contract with adopters is the DoR Gate; whatever feeds the gate is the adopter's choice. See docs/concepts/spec-driven.md §5 ("When to skip tiers") for guidance.

Architecture Overview

The framework is built on five resource types organized in a four-layer model:

┌──────────────────────────────────────────┐
│           Pipeline                        │  Orchestration: triggers, stages, routing
├──────────────────────────────────────────┤
│    AgentRole    │    QualityGate          │  Behavior: agents + enforcement
├──────────────────────────────────────────┤
│         AutonomyPolicy                    │  Governance: trust levels + promotion
├──────────────────────────────────────────┤
│         AdapterBinding                    │  Integration: tool connections
└──────────────────────────────────────────┘

Prerequisites

• Node.js >= 20
• pnpm >= 9

Installation

Orchestrator (CLI)

npm install -g @ai-sdlc/orchestrator

# Initialize in your repository
ai-sdlc init

# Run a pipeline for a single issue
ai-sdlc run --issue 42

Agent runners

The orchestrator auto-discovers available runners from environment variables:

# Claude Code (always available as default runner)
# Copilot — set GH_TOKEN or GITHUB_TOKEN
export GH_TOKEN=ghp_...

# Cursor — set CURSOR_API_KEY
export CURSOR_API_KEY=cur_...

# Codex — set CODEX_API_KEY
export CODEX_API_KEY=cdx_...

# Any OpenAI-compatible API — set OPENAI_API_KEY or LLM_API_KEY + LLM_API_URL
export OPENAI_API_KEY=sk-...

# Ollama (local models, incl. Gemma) — set OLLAMA_MODEL; runs via the
# OpenAI-compatible GenericLLMRunner path, no dedicated runner needed.
# See "Ollama (local models)" in the Runners Reference for the full recipe.
export OLLAMA_MODEL=gemma4:31b

For SDK users

npm install @ai-sdlc/reference
# or
pnpm add @ai-sdlc/reference

For contributors

git clone https://github.com/ai-sdlc-framework/ai-sdlc.git
cd ai-sdlc
pnpm install
pnpm build

Core Concepts

• Resource envelope -- Every resource has apiVersion, kind, metadata, and spec. Optional status is set by the runtime.
• Enforcement levels -- Gates use advisory (log only), soft-mandatory (block with override), or hard-mandatory (block always).
• Autonomy levels -- Agents progress through Intern (0), Junior (1), Senior (2), Principal (3) by meeting quantitative criteria.
• Adapter interfaces -- Six core contracts (IssueTracker, SourceControl, CIPipeline, CodeAnalysis, Messenger, DeploymentTarget) plus infrastructure interfaces.
• Reconciliation loop -- A controller pattern that continuously drives actual state toward desired state.

Validate Schemas

pnpm --filter @ai-sdlc/reference validate-schemas

Your First Pipeline

As YAML

Create a pipeline.yaml:

apiVersion: ai-sdlc.io/v1alpha1
kind: Pipeline
metadata:
  name: my-first-pipeline
spec:
  triggers:
    - event: issue.assigned
  providers:
    issueTracker:
      type: linear
  stages:
    - name: implement
      agent: code-agent
    - name: review
      agent: reviewer-agent

Using the Builder API

import { PipelineBuilder, validateResource } from '@ai-sdlc/reference';

const pipeline = new PipelineBuilder('my-first-pipeline')
  .addTrigger({ event: 'issue.assigned' })
  .addProvider('issueTracker', { type: 'linear' })
  .addStage({ name: 'implement', agent: 'code-agent' })
  .addStage({ name: 'review', agent: 'reviewer-agent' })
  .build();

const result = validateResource(pipeline);
console.log(result.valid); // true

Validating Resources Programmatically

The SDK validates resources against JSON Schema (draft 2020-12):

import { validate, validateResource } from '@ai-sdlc/reference';
import { readFileSync } from 'fs';
import { parse } from 'yaml';

// Option 1: Infer kind from document
const doc = parse(readFileSync('pipeline.yaml', 'utf-8'));
const result = validateResource(doc);

// Option 2: Specify kind explicitly
const result2 = validate('Pipeline', doc);

if (!result.valid) {
  for (const err of result.errors!) {
    console.error(`${err.path}: ${err.message}`);
  }
}

Your First Quality Gate

import { QualityGateBuilder, enforce } from '@ai-sdlc/reference';

const gate = new QualityGateBuilder('code-standards')
  .addGate({
    name: 'test-coverage',
    enforcement: 'soft-mandatory',
    rule: { metric: 'line-coverage', operator: '>=', threshold: 80 },
    override: { requiredRole: 'engineering-manager', requiresJustification: true },
  })
  .addGate({
    name: 'security-scan',
    enforcement: 'hard-mandatory',
    rule: { tool: 'semgrep', maxSeverity: 'medium' },
  })
  .build();

// Evaluate the gate
const result = enforce(gate, {
  authorType: 'ai-agent',
  repository: 'org/my-service',
  metrics: { 'line-coverage': 85 },
  toolResults: { semgrep: { findings: [] } },
});

console.log(result.allowed); // true
console.log(result.results.map(r => `${r.gate}: ${r.verdict}`));
// ['test-coverage: pass', 'security-scan: pass']

Running the Dogfood Pipeline

The repository includes a self-hosted pipeline that uses the framework to manage its own development:

# Run the dogfood pipeline tests
pnpm --filter @ai-sdlc/dogfood test

# Run all tests across the monorepo
pnpm test

Next Steps

• Onboarding guide -- Start here for new adopters. Covers prerequisites, install, signing-key init, .ai-sdlc/ scaffold, first task execution, and first attested PR — including a "Found Gaps" section listing hidden prerequisites. End-to-end validation on a non-author repository is pending (see guide for AC#2 status).
• Spec-Kit Bridge tutorial -- Recommended adopter authoring path. End-to-end walkthrough: install spec-kit → author spec → import → DoR-at-import → dispatch → ship → handle drift (RFC-0036).
• Concepts: spec-driven development -- The three-tier authoring model (RFC → Spec → Task), Decision-Engine framing, and the seam contract.
• Runners Reference -- All supported agent runners and configuration
• Tutorials -- Step-by-step walkthroughs for pipelines, gates, autonomy, adapters, and orchestration
• API Reference -- Complete SDK and orchestrator reference
• Architecture -- Package structure, data flow, and design patterns
• Troubleshooting -- Common issues and solutions
• Primer -- Conceptual introduction to the framework
• Specification -- Full normative spec for implementors
• Examples -- Complete working examples